peer channel

The peer channel command allows administrators to perform channel related operations on a peer, such as joining a channel or listing the channels to which a peer is joined.

Syntax

The peer channel command has the following subcommands:

  • create

  • fetch

  • getinfo

  • join

  • joinbysnapshot

  • joinbysnapshotstatus

  • list

  • signconfigtx

  • update

peer channel

  1. Operate a channel: create|fetch|join|joinbysnapshot|joinbysnapshotstatus|list|update|signconfigtx|getinfo.
  3. Usage:
  4.   peer channel [command]
  6. Available Commands:
  7.   create               Create a channel
  8.   fetch                Fetch a block
  9.   getinfo              get blockchain information of a specified channel.
  10.   join                 Joins the peer to a channel.
  11.   joinbysnapshot       Joins the peer to a channel by the specified snapshot
  12.   joinbysnapshotstatus Query if joinbysnapshot is running for any channel
  13.   list                 List of channels peer has joined.
  14.   signconfigtx         Signs a configtx update.
  15.   update               Send a configtx update.
  17. Flags:
  18.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  19.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  20.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  21.       --connTimeout duration                Timeout for client to connect (default 3s)
  22.   -h, --help                                help for channel
  23.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  24.   -o, --orderer string                      Ordering service endpoint
  25.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  26.       --tls                                 Use TLS when communicating with the orderer endpoint
  27.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint
  29. Use "peer channel [command] --help" for more information about a command.

peer channel create

  1. Create a channel and write the genesis block to a file.
  3. Usage:
  4.   peer channel create [flags]
  6. Flags:
  7.   -c, --channelID string     In case of a newChain command, the channel ID to create. It must be all lower case, less than 250 characters long and match the regular expression: [a-z][a-z0-9.-]*
  8.   -f, --file string          Configuration transaction file generated by a tool such as configtxgen for submitting to orderer
  9.   -h, --help                 help for create
  10.       --outputBlock string   The path to write the genesis block for the channel. (default ./<channelID>.block)
  11.   -t, --timeout duration     Channel creation timeout (default 10s)
  13. Global Flags:
  14.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  15.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  16.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  17.       --connTimeout duration                Timeout for client to connect (default 3s)
  18.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  19.   -o, --orderer string                      Ordering service endpoint
  20.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  21.       --tls                                 Use TLS when communicating with the orderer endpoint
  22.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel fetch

  1. Fetch a specified block, writing it to a file.
  3. Usage:
  4.   peer channel fetch <newest|oldest|config|(number)> [outputfile] [flags]
  6. Flags:
  7.       --bestEffort         Whether fetch requests should ignore errors and return blocks on a best effort basis
  8.   -c, --channelID string   In case of a newChain command, the channel ID to create. It must be all lower case, less than 250 characters long and match the regular expression: [a-z][a-z0-9.-]*
  9.   -h, --help               help for fetch
  11. Global Flags:
  12.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  13.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  14.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  15.       --connTimeout duration                Timeout for client to connect (default 3s)
  16.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  17.   -o, --orderer string                      Ordering service endpoint
  18.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  19.       --tls                                 Use TLS when communicating with the orderer endpoint
  20.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel getinfo

  1. get blockchain information of a specified channel. Requires '-c'.
  3. Usage:
  4.   peer channel getinfo [flags]
  6. Flags:
  7.   -c, --channelID string   In case of a newChain command, the channel ID to create. It must be all lower case, less than 250 characters long and match the regular expression: [a-z][a-z0-9.-]*
  8.   -h, --help               help for getinfo
  10. Global Flags:
  11.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  12.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  13.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  14.       --connTimeout duration                Timeout for client to connect (default 3s)
  15.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  16.   -o, --orderer string                      Ordering service endpoint
  17.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  18.       --tls                                 Use TLS when communicating with the orderer endpoint
  19.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel join

  1. Joins the peer to a channel.
  3. Usage:
  4.   peer channel join [flags]
  6. Flags:
  7.   -b, --blockpath string   Path to file containing genesis block
  8.   -h, --help               help for join
  10. Global Flags:
  11.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  12.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  13.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  14.       --connTimeout duration                Timeout for client to connect (default 3s)
  15.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  16.   -o, --orderer string                      Ordering service endpoint
  17.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  18.       --tls                                 Use TLS when communicating with the orderer endpoint
  19.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel joinbysnapshot

  1. Joins the peer to a channel by the specified snapshot
  3. Usage:
  4.   peer channel joinbysnapshot [flags]
  6. Flags:
  7.   -h, --help                  help for joinbysnapshot
  8.       --snapshotpath string   Path to the snapshot directory
  10. Global Flags:
  11.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  12.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  13.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  14.       --connTimeout duration                Timeout for client to connect (default 3s)
  15.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  16.   -o, --orderer string                      Ordering service endpoint
  17.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  18.       --tls                                 Use TLS when communicating with the orderer endpoint
  19.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel joinbysnapshotstatus

  1. Query if joinbysnapshot is running for any channel
  3. Usage:
  4.   peer channel joinbysnapshotstatus [flags]
  6. Flags:
  7.   -h, --help   help for joinbysnapshotstatus
  9. Global Flags:
  10.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  11.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  12.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  13.       --connTimeout duration                Timeout for client to connect (default 3s)
  14.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  15.   -o, --orderer string                      Ordering service endpoint
  16.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  17.       --tls                                 Use TLS when communicating with the orderer endpoint
  18.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel list

  1. List of channels peer has joined.
  3. Usage:
  4.   peer channel list [flags]
  6. Flags:
  7.   -h, --help   help for list
  9. Global Flags:
  10.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  11.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  12.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  13.       --connTimeout duration                Timeout for client to connect (default 3s)
  14.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  15.   -o, --orderer string                      Ordering service endpoint
  16.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  17.       --tls                                 Use TLS when communicating with the orderer endpoint
  18.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel signconfigtx

  1. Signs the supplied configtx update file in place on the filesystem. Requires '-f'.
  3. Usage:
  4.   peer channel signconfigtx [flags]
  6. Flags:
  7.   -f, --file string   Configuration transaction file generated by a tool such as configtxgen for submitting to orderer
  8.   -h, --help          help for signconfigtx
  10. Global Flags:
  11.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  12.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  13.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  14.       --connTimeout duration                Timeout for client to connect (default 3s)
  15.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  16.   -o, --orderer string                      Ordering service endpoint
  17.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  18.       --tls                                 Use TLS when communicating with the orderer endpoint
  19.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

peer channel update

  1. Signs and sends the supplied configtx update file to the channel. Requires '-f', '-o', '-c'.
  3. Usage:
  4.   peer channel update [flags]
  6. Flags:
  7.   -c, --channelID string   In case of a newChain command, the channel ID to create. It must be all lower case, less than 250 characters long and match the regular expression: [a-z][a-z0-9.-]*
  8.   -f, --file string        Configuration transaction file generated by a tool such as configtxgen for submitting to orderer
  9.   -h, --help               help for update
  11. Global Flags:
  12.       --cafile string                       Path to file containing PEM-encoded trusted certificate(s) for the ordering endpoint
  13.       --certfile string                     Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the orderer endpoint
  14.       --clientauth                          Use mutual TLS when communicating with the orderer endpoint
  15.       --connTimeout duration                Timeout for client to connect (default 3s)
  16.       --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
  17.   -o, --orderer string                      Ordering service endpoint
  18.       --ordererTLSHostnameOverride string   The hostname override to use when validating the TLS connection to the orderer
  19.       --tls                                 Use TLS when communicating with the orderer endpoint
  20.       --tlsHandshakeTimeShift duration      The amount of time to shift backwards for certificate expiration checks during TLS handshakes with the orderer endpoint

Example Usage

peer channel create examples

Here’s an example that uses the --orderer global flag on the peer channel create command.

  • Create a sample channel mychannel defined by the configuration transaction contained in file ./createchannel.tx. Use the orderer at orderer.example.com:7050.

    1. peer channel create -c mychannel -f ./createchannel.tx --orderer orderer.example.com:7050
    3. 2018-02-25 08:23:57.548 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. 2018-02-25 08:23:57.626 UTC [channelCmd] InitCmdFactory -> INFO 019 Endorser and orderer connections initialized
    5. 2018-02-25 08:23:57.834 UTC [channelCmd] readBlock -> INFO 020 Received block: 0
    6. 2018-02-25 08:23:57.835 UTC [main] main -> INFO 021 Exiting.....

    Block 0 is returned indicating that the channel has been successfully created.

Here’s an example of the peer channel create command option.

  • Create a new channel mychannel for the network, using the orderer at ip address orderer.example.com:7050. The configuration update transaction required to create this channel is defined the file ./createchannel.tx. Wait 30 seconds for the channel to be created.

    1.   peer channel create -c mychannel --orderer orderer.example.com:7050 -f ./createchannel.tx -t 30s
    3.   2018-02-23 06:31:58.568 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4.   2018-02-23 06:31:58.669 UTC [channelCmd] InitCmdFactory -> INFO 019 Endorser and orderer connections initialized
    5.   2018-02-23 06:31:58.877 UTC [channelCmd] readBlock -> INFO 020 Received block: 0
    6.   2018-02-23 06:31:58.878 UTC [main] main -> INFO 021 Exiting.....
    8.   ls -l
    10.   -rw-r--r-- 1 root root 11982 Feb 25 12:24 mychannel.block

    You can see that channel mychannel has been successfully created, as indicated in the output where block 0 (zero) is added to the blockchain for this channel and returned to the peer, where it is stored in the local directory as mychannel.block.

    Block zero is often called the genesis block as it provides the starting configuration for the channel. All subsequent updates to the channel will be captured as configuration blocks on the channel’s blockchain, each of which supersedes the previous configuration.

peer channel fetch example

Here’s some examples of the peer channel fetch command.

  • Using the newest option to retrieve the most recent channel block, and store it in the file mychannel.block.

    1. peer channel fetch newest mychannel.block -c mychannel --orderer orderer.example.com:7050
    3. 2018-02-25 13:10:16.137 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. 2018-02-25 13:10:16.144 UTC [channelCmd] readBlock -> INFO 00a Received block: 32
    5. 2018-02-25 13:10:16.145 UTC [main] main -> INFO 00b Exiting.....
    7. ls -l
    9. -rw-r--r-- 1 root root 11982 Feb 25 13:10 mychannel.block

    You can see that the retrieved block is number 32, and that the information has been written to the file mychannel.block.

  • Using the (block number) option to retrieve a specific block – in this case, block number 16 – and store it in the default block file.

    1. peer channel fetch 16  -c mychannel --orderer orderer.example.com:7050
    3. 2018-02-25 13:46:50.296 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. 2018-02-25 13:46:50.302 UTC [channelCmd] readBlock -> INFO 00a Received block: 16
    5. 2018-02-25 13:46:50.302 UTC [main] main -> INFO 00b Exiting.....
    7. ls -l
    9. -rw-r--r-- 1 root root 11982 Feb 25 13:10 mychannel.block
    10. -rw-r--r-- 1 root root  4783 Feb 25 13:46 mychannel_16.block

    You can see that the retrieved block is number 16, and that the information has been written to the default file mychannel_16.block.

    For configuration blocks, the block file can be decoded using the configtxlator command. See this command for an example of decoded output. User transaction blocks can also be decoded, but a user program must be written to do this.

peer channel getinfo example

Here’s an example of the peer channel getinfo command.

  • Get information about the local peer for channel mychannel.

    1. peer channel getinfo -c mychannel
    3. 2018-02-25 15:15:44.135 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. Blockchain info: {"height":5,"currentBlockHash":"JgK9lcaPUNmFb5Mp1qe1SVMsx3o/22Ct4+n5tejcXCw=","previousBlockHash":"f8lZXoAn3gF86zrFq7L1DzW2aKuabH9Ow6SIE5Y04a4="}
    5. 2018-02-25 15:15:44.139 UTC [main] main -> INFO 006 Exiting.....

    You can see that the latest block for channel mychannel is block 5. You can also see the cryptographic hashes for the most recent blocks in the channel’s blockchain.

peer channel join example

Here’s an example of the peer channel join command.

  • Join a peer to the channel defined in the genesis block identified by the file ./mychannel.genesis.block. In this example, the channel block was previously retrieved by the peer channel fetch command.

    1. peer channel join -b ./mychannel.genesis.block
    3. 2018-02-25 12:25:26.511 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. 2018-02-25 12:25:26.571 UTC [channelCmd] executeJoin -> INFO 006 Successfully submitted proposal to join channel
    5. 2018-02-25 12:25:26.571 UTC [main] main -> INFO 007 Exiting.....

    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.

    1. peer channel joinbysnapshot --snapshotpath /snapshots/completed/testchannel/1000
    3. 2020-10-12 11:41:45.442 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
    4. 2020-10-12 11:41:45.444 EDT [channelCmd] executeJoin -> INFO 002 Successfully submitted proposal to join channel
    5. 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.

    1. peer channel joinbysnapshotstatus
    3. 2020-10-12 11:41:45.952 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
    4. 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.

    1. peer channel joinbysnapshotstatus
    3. 2020-10-12 11:41:47.922 EDT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
    4. No joinbysnapshot operation is in progress

peer channel list example

Here’s an example of the peer channel list command.

  • List the channels to which a peer is joined.

    1. peer channel list
    3. 2018-02-25 14:21:20.361 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. Channels peers has joined:
    5. mychannel
    6. 2018-02-25 14:21:20.372 UTC [main] main -> INFO 006 Exiting.....

    You can see that the peer is joined to channel mychannel.

peer channel signconfigtx example

Here’s an example of the peer channel signconfigtx command.

  • Sign the channel update transaction defined in the file ./updatechannel.tx. The example lists the configuration transaction file before and after the command.

    1. ls -l
    3. -rw-r--r--  1 anthonyodowd  staff   284 25 Feb 18:16 updatechannel.tx
    5. peer channel signconfigtx -f updatechannel.tx
    7. 2018-02-25 18:16:44.456 GMT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
    8. 2018-02-25 18:16:44.459 GMT [main] main -> INFO 002 Exiting.....
    10. ls -l
    12. -rw-r--r--  1 anthonyodowd  staff  2180 25 Feb 18:16 updatechannel.tx

    You can see that the peer has successfully signed the configuration transaction by the increase in the size of the file updatechannel.tx from 284 bytes to 2180 bytes.

peer channel update example

Here’s an example of the peer channel update command.

  • Update the channel mychannel using the configuration transaction defined in the file ./updatechannel.tx. Use the orderer at ip address orderer.example.com:7050 to send the configuration transaction to all peers in the channel to update their copy of the channel configuration.

    1. peer channel update -c mychannel -f ./updatechannel.tx -o orderer.example.com:7050
    3. 2018-02-23 06:32:11.569 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
    4. 2018-02-23 06:32:11.626 UTC [main] main -> INFO 010 Exiting.....

    At this point, the channel mychannel has been successfully updated.

Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.