Add doc files for peer snapshot commands

Signed-off-by: Wenjian Qiao <[email protected]>
hyperledger · Oct 28, 2020 · dedcf42 · dedcf42
1 parent cf678be
commit dedcf42
Show file tree

Hide file tree

Showing 9 changed files with 366 additions and 9 deletions.
diff --git a/docs/source/command_ref.rst b/docs/source/command_ref.rst
@@ -8,6 +8,7 @@ Commands Reference
    commands/peerchaincode.md
    commands/peerlifecycle.md
    commands/peerchannel.md
+   commands/peersnapshot.md
    commands/peerversion.md
    commands/peernode.md
    commands/configtxgen.md

diff --git a/docs/source/commands/peerchannel.md b/docs/source/commands/peerchannel.md
@@ -12,25 +12,29 @@ The `peer channel` command has the following subcommands:
   * fetch
   * getinfo
   * join
+  * joinbysnapshot
+  * joinbysnapshotstatus
   * list
   * signconfigtx
   * update
 
 ## peer channel
 ```
-Operate a channel: create|fetch|join|list|update|signconfigtx|getinfo.
+Operate a channel: create|fetch|join|joinbysnapshot|joinbysnapshotstatus|list|update|signconfigtx|getinfo.
 
 Usage:
   peer channel [command]
 
 Available Commands:
-  create       Create a channel
-  fetch        Fetch a block
-  getinfo      get blockchain information of a specified channel.
-  join         Joins the peer to a channel.
-  list         List of channels peer has joined.
-  signconfigtx Signs a configtx update.
-  update       Send a configtx update.
+  create               Create a channel
+  fetch                Fetch a block
+  getinfo              get blockchain information of a specified channel.
+  join                 Joins the peer to a channel.
+  joinbysnapshot       Joins the peer to a channel by the specified snapshot
+  joinbysnapshotstatus Query if joinbysnapshot is running for any channel
+  list                 List of channels peer has joined.
+  signconfigtx         Signs a configtx update.
+  update               Send a configtx update.
 
 Flags:
       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
@@ -148,6 +152,53 @@ Global Flags:
 ```
 
 
+## peer channel joinbysnapshot
+```
+Joins the peer to a channel by the specified snapshot
+
+Usage:
+  peer channel joinbysnapshot [flags]
+
+Flags:
+  -h, --help                  help for joinbysnapshot
+      --snapshotpath string   Path to the snapshot directory
+
+Global Flags:
+      --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
+      --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
+      --clientauth                          Use mutual TLS when communicating with the orderer endpoint
+      --connTimeout duration                Timeout for client to connect (default 3s)
+      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
+  -o, --orderer string                      Ordering service endpoint
+      --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
+      --tls                                 Use TLS when communicating with the orderer endpoint
+      --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint
+```
+
+
+## peer channel joinbysnapshotstatus
+```
+Query if joinbysnapshot is running for any channel
+
+Usage:
+  peer channel joinbysnapshotstatus [flags]
+
+Flags:
+  -h, --help   help for joinbysnapshotstatus
+
+Global Flags:
+      --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
+      --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
+      --clientauth                          Use mutual TLS when communicating with the orderer endpoint
+      --connTimeout duration                Timeout for client to connect (default 3s)
+      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
+  -o, --orderer string                      Ordering service endpoint
+      --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
+      --tls                                 Use TLS when communicating with the orderer endpoint
+      --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint
+```
+
+
 ## peer channel list
 ```
 List of channels peer has joined.
@@ -358,6 +409,52 @@ Here's an example of the `peer channel join` command.
 
   You can see that the peer has successfully made a request to join the channel.
 
+### peer channel joinbysnapshot example
+
+Here's an example of the `peer channel joinbysnapshot` command.
+
+* Join a peer to the channel from a snapshot identified by the directory
+  `/snapshots/completed/testchannel/1000`. The snapshot was previously created on a different peer.
+
+  ```
+  peer channel joinbysnapshot --snapshotpath /snapshots/completed/testchannel/1000
+
+  2020-10-12 11:41:45.442 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
+  2020-10-12 11:41:45.444 EDT [channelCmd] executeJoin -> INFO 002 Successfully submitted proposal to join channel
+  2020-10-12 11:41:45.444 EDT [channelCmd] joinBySnapshot -> INFO 003 The joinbysnapshot operation is in progress. Use "peer channel joinbysnapshotstatus" to check the status.
+
+  ```
+
+  You can see that the peer has successfully made a request to join the channel from the specified snapshot.
+  When a `joinbysnapshot` operation is in progress, you cannot run another `peer channel join`
+  or `peer channel joinbysnapshot` simultaneously. To know whether or not a joinbysnapshot operation is in progress,
+  you can call the `peer channel joinbysnapshotstatus` command.
+
+
+### peer channel joinbysnapshotstatus example
+
+Here are some examples of the `peer channel joinbysnapshotstatus` command.
+
+* Query if joinbysnapshot is in progress for any channel. If yes,
+  it returns a message indicating a joinbysnapshot operation is in progress.
+
+  ```
+  peer channel joinbysnapshotstatus
+
+  2020-10-12 11:41:45.952 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
+  A joinbysnapshot operation is in progress for snapshot at /snapshots/completed/testchannel/1000
+  ```
+
+* If no `joinbysnapshot` operation is in progress, it returns a message indicating no joinbysnapshot operation is in progress.
+
+  ```
+  peer channel joinbysnapshotstatus
+
+  2020-10-12 11:41:47.922 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
+  No joinbysnapshot operation is in progress
+
+  ```
+
 ### peer channel list example
 
   Here's an example of the `peer channel list` command.

diff --git a/docs/source/commands/peerlifecycle.md b/docs/source/commands/peerlifecycle.md
@@ -120,6 +120,7 @@ Flags:
       --connectionProfile string       The fully qualified path to the connection profile that provides the necessary connection information for the network. Note: currently only supported for providing peer connection information
   -h, --help                           help for install
       --peerAddresses stringArray      The addresses of the peers to connect to
+      --targetPeer string              When using a connection profile, the name of the peer to target for this action
       --tlsRootCertFiles stringArray   If TLS is enabled, the paths to the TLS root cert files of the peers to connect to. The order and number of certs specified should match the --peerAddresses flag
 
 Global Flags:
@@ -147,6 +148,7 @@ Flags:
   -h, --help                           help for queryinstalled
   -O, --output string                  The output format for query results. Default is human-readable plain-text. json is currently the only supported format.
       --peerAddresses stringArray      The addresses of the peers to connect to
+      --targetPeer string              When using a connection profile, the name of the peer to target for this action
       --tlsRootCertFiles stringArray   If TLS is enabled, the paths to the TLS root cert files of the peers to connect to. The order and number of certs specified should match the --peerAddresses flag
 
 Global Flags:
@@ -175,6 +177,7 @@ Flags:
       --output-directory string        The output directory to use when writing a chaincode install package to disk. Default is the current working directory.
       --package-id string              The identifier of the chaincode install package
       --peerAddresses stringArray      The addresses of the peers to connect to
+      --targetPeer string              When using a connection profile, the name of the peer to target for this action
       --tlsRootCertFiles stringArray   If TLS is enabled, the paths to the TLS root cert files of the peers to connect to. The order and number of certs specified should match the --peerAddresses flag
 
 Global Flags:

diff --git a/docs/source/commands/peersnapshot.md b/docs/source/commands/peersnapshot.md
@@ -0,0 +1,124 @@
+# peer snapshot
+
+The `peer snapshot` command allows administrators to perform snapshot related
+operations on a peer, such as submit a snapshot request, cancel a snapshot request
+and list pending requests. Once a snapshot request is submitted for a specified
+block number, the snapshot will be automatically generated when the block number is
+committed on the channel.
+
+## Syntax
+
+The `peer snapshot` command has the following subcommands:
+
+  * cancelrequest
+  * listpending
+  * submitrequest
+
+## peer snapshot cancelrequest
+```
+Cancel a request for a snapshot at the specified block.
+
+Usage:
+  peer snapshot cancelrequest [flags]
+
+Flags:
+  -b, --blockNumber uint         The block number for which a snapshot will be generated
+  -C, --channelID string         The channel on which this command should be executed
+  -h, --help                     help for cancelrequest
+      --peerAddress string       The address of the peer to connect to
+      --tlsRootCertFile string   The path to the TLS root cert file of the peer to connect to, required if TLS is enabled and ignored if TLS is disabled.
+```
+
+
+## peer snapshot listpending
+```
+List pending requests for snapshots.
+
+Usage:
+  peer snapshot listpending [flags]
+
+Flags:
+  -C, --channelID string         The channel on which this command should be executed
+  -h, --help                     help for listpending
+      --peerAddress string       The address of the peer to connect to
+      --tlsRootCertFile string   The path to the TLS root cert file of the peer to connect to, required if TLS is enabled and ignored if TLS is disabled.
+```
+
+
+## peer snapshot submitrequest
+```
+Submit a request for a snapshot at the specified block. When the blockNumber parameter is set to 0 or not provided, it will submit a request for the last committed block.
+
+Usage:
+  peer snapshot submitrequest [flags]
+
+Flags:
+  -b, --blockNumber uint         The block number for which a snapshot will be generated
+  -C, --channelID string         The channel on which this command should be executed
+  -h, --help                     help for submitrequest
+      --peerAddress string       The address of the peer to connect to
+      --tlsRootCertFile string   The path to the TLS root cert file of the peer to connect to, required if TLS is enabled and ignored if TLS is disabled.
+```
+
+## Example Usage
+
+### peer snapshot cancelrequest example
+
+Here is an example of the `peer snapshot cancelrequest` command.
+
+  * Cancel a snapshot request for block number 1000 on channel `mychannel`
+    for `peer0.org1.example.com:7051`:
+
+    ```
+    peer snapshot cancelrequest -C mychannel -b 1000 --peerAddress peer0.org1.example.com:7051
+
+    Snapshot request cancelled successfully
+
+    ```
+
+    A successful response indicates that the snapshot request for block number 1000 has been removed from `mychannel`.
+    If there is no pending snapshot request for block number 1000, the command will return an error.
+
+  * Use the `--tlsRootCertFile` flag in a network with TLS enabled
+
+### peer snapshot listpending example
+
+Here is an example of the `peer snapshot listpending` command.
+If a snapshot is already generated, the corresponding block number will be removed from the pending list.
+
+  * List pending snapshot requests on channel `mychannel`
+    for `peer0.org1.example.com:7051`:
+
+    ```
+    peer snapshot listpending -C mychannel --peerAddress peer0.org1.example.com:7051
+
+    Successfully got pending snapshot requests: [1000 5000]
+
+    ```
+
+    You can see that the command returns a list of block numbers for the pending snapshot requests.
+
+  * Use the `--tlsRootCertFile` flag in a network with TLS enabled
+
+### peer snapshot submitrequest example
+
+Here is an example of the `peer snapshot submitrequest` command.
+
+  * Submit a snapshot request for block number 1000 on channel `mychannel`
+    for `peer0.org1.example.com:7051`:
+
+    ```
+    peer snapshot submitrequest -C mychannel -b 1000 --peerAddress peer0.org1.example.com:7051
+
+    Snapshot request submitted successfully
+
+    ```
+
+    You can see that the snapshot request is successfully submitted on channel `mychannel`.
+    A snapshot will be automatically generated after the block number 1000 is committed on the channel.
+
+    The specified block number must be at or above the last block number on the channel.
+    Otherwise, the command will return an error.
+
+  * Use the `--tlsRootCertFile` flag in a network with TLS enabled
+
diff --git a/docs/wrappers/peer_channel_postscript.md b/docs/wrappers/peer_channel_postscript.md
@@ -137,6 +137,52 @@ Here's an example of the `peer channel join` command.
 
   You can see that the peer has successfully made a request to join the channel.
 
+### peer channel joinbysnapshot example
+
+Here's an example of the `peer channel joinbysnapshot` command.
+
+* Join a peer to the channel from a snapshot identified by the directory
+  `/snapshots/completed/testchannel/1000`. The snapshot was previously created on a different peer.
+
+  ```
+  peer channel joinbysnapshot --snapshotpath /snapshots/completed/testchannel/1000
+
+  2020-10-12 11:41:45.442 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
+  2020-10-12 11:41:45.444 EDT [channelCmd] executeJoin -> INFO 002 Successfully submitted proposal to join channel
+  2020-10-12 11:41:45.444 EDT [channelCmd] joinBySnapshot -> INFO 003 The joinbysnapshot operation is in progress. Use "peer channel joinbysnapshotstatus" to check the status.
+
+  ```
+
+  You can see that the peer has successfully made a request to join the channel from the specified snapshot.
+  When a `joinbysnapshot` operation is in progress, you cannot run another `peer channel join`
+  or `peer channel joinbysnapshot` simultaneously. To know whether or not a joinbysnapshot operation is in progress,
+  you can call the `peer channel joinbysnapshotstatus` command.
+
+
+### peer channel joinbysnapshotstatus example
+
+Here are some examples of the `peer channel joinbysnapshotstatus` command.
+
+* Query if joinbysnapshot is in progress for any channel. If yes,
+  it returns a message indicating a joinbysnapshot operation is in progress.
+
+  ```
+  peer channel joinbysnapshotstatus
+
+  2020-10-12 11:41:45.952 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
+  A joinbysnapshot operation is in progress for snapshot at /snapshots/completed/testchannel/1000
+  ```
+
+* If no `joinbysnapshot` operation is in progress, it returns a message indicating no joinbysnapshot operation is in progress.
+
+  ```
+  peer channel joinbysnapshotstatus
+
+  2020-10-12 11:41:47.922 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
+  No joinbysnapshot operation is in progress
+
+  ```
+
 ### peer channel list example
 
   Here's an example of the `peer channel list` command.

diff --git a/docs/wrappers/peer_channel_preamble.md b/docs/wrappers/peer_channel_preamble.md
@@ -12,6 +12,8 @@ The `peer channel` command has the following subcommands:
   * fetch
   * getinfo
   * join
+  * joinbysnapshot
+  * joinbysnapshotstatus
   * list
   * signconfigtx
   * update