peer channel

Description

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 syntax:

peer channel create       [flags]
peer channel fetch        [flags]
peer channel getinfo      [flags]
peer channel join         [flags]
peer channel list         [flags]
peer channel signconfigtx [flags]
peer channel update       [flags]

For brevity, we often refer to a command (peer), a subcommand (channel), or subcommand option (fetch) simply as a command.

The different command options (create, fetch...) relate to the different channel operations that are relevant to a peer. For example, use the peer channel join command to join a peer to a channel, or the peer channel list command to show the channels to which a peer is joined.

Each peer channel subcommand is described together with its options in its own section in this topic.

Flags

Each peer channel command option has a set of flags specific to it, and these are described with the relevant subcommand option.

All peer channel command options also have a set of global flags that can be applied to peer channel command options.

The global flags are as follows:

  • --cafile <string>

    where <string> is a fully qualified path to a file containing a PEM-encoded certificate chain of the Certificate Authority of the orderer with whom the peer is communicating. Use in conjunction with the --tls flag.

  • --certfile <string>

    where <string> is a fully qualified path to a file containing a PEM-encoded X.509 certificate used for mutual authentication with the orderer. Use in conjunction with the --clientauth flag.

  • --clientauth

    Use this flag to enable mutual TLS communication with the orderer. Use in conjunction with the --certfile and --keyfile flags.

  • --keyfile <string>

    where <string> is a fully qualified path to a file containing a PEM-encoded X.509 private key used for mutual authentication with the orderer. Use in conjunction with the --clientauth flag.

  • -o, --orderer <string>

    where <string> is the fully qualified address and port of the orderer with whom the peer is communicating. If the port is not specified, it will default to port 7050.

  • --ordererTLSHostnameOverride <string>

    where <string> is the hostname override to use when using TLS to communicate with the orderer specified by the --orderer flag. It is necessary to use this flag when the TLS handshake phase of communications between the peer and the orderer uses a different hostname than the subsequent message exchange phase. Use in conjunction with the --tls flag.

  • --tls

    Use this flag to enable TLS communications with an orderer. The certificates identified by --cafile will be used by TLS to authenticate the orderer.

Usage

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.txn. Use the orderer at orderer.example.com:7050.

    peer channel create -c mychannel -f ./createchannel.txn --orderer orderer.example.com:7050

2018-02-25 08:23:57.548 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
2018-02-25 08:23:57.626 UTC [channelCmd] InitCmdFactory -> INFO 019 Endorser and orderer connections initialized
2018-02-25 08:23:57.834 UTC [channelCmd] readBlock -> DEBU 020 Received block: 0
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.

peer channel create

Create Description

The peer channel create command allows administrators to create a new channel. This command connects to an orderer to perform this function -- it is not performed on the peer, even though the peer command is used.

To create a channel, the administrator uses the command to submit a configuration update transaction to the orderer. This transaction describes the configuration changes required to create a new channel. Moreover, this transaction must be signed by the required organizations as defined by the current orderer configuration. Configuration transactions can be generated by the configtxgen command and signed by the peer channel signconfigtx command.

Create Syntax

The peer channel create command has the following syntax:

peer channel create [flags]

Create Flags

The peer channel create command has the following command specific flags:

  • -c, --channelID <string>

    required, where <string> is the name of the channel which is to be created.

  • -f, --file <string>

    required, where <string> identifies a file which contains the configuration transaction required to create this channel. It can be generated by configtxgen command.

  • -t, --timeout <integer>

    optional, where <integer> specifies channel creation timeout in seconds. If not specified, the default is 5 seconds. Note that if the command times out, then the channel may or may not have been created.

The global peer command flags also apply as follows:

  • -o, --orderer required
  • --cafile optional
  • --certfile optional
  • --clientuth optional
  • --keyfile optional
  • --ordererTLSHostnameOverride optional
  • --tls optional

Create Usage

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.txn. Wait 30 seconds for the channel to be created.

    peer channel create -c mychannel --orderer orderer.example.com:7050 -f ./createchannel.txn -t 30

2018-02-23 06:31:58.568 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
2018-02-23 06:31:58.669 UTC [channelCmd] InitCmdFactory -> INFO 019 Endorser and orderer connections initialized
2018-02-23 06:31:58.877 UTC [channelCmd] readBlock -> DEBU 020 Received block: 0
2018-02-23 06:31:58.878 UTC [main] main -> INFO 021 Exiting.....

ls -l

-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

Fetch Description

The peer channel fetch command allows a client to fetch a block from the orderer. The block may contain a configuration transaction or user transactions.

The client must have read access to the channel. This command connects to an orderer to perform this function -- it is not performed on the peer, even though the peer client command is used.

Fetch Syntax

The peer channel fetch command has the following syntax:

peer channel fetch [newest|oldest|config|(block number)] [<outputFile>] [flags]

where

  • newest

    returns the most recent block available at the orderer for the channel. This may be a user transaction block or a configuration block.

    This option will also return the block number of the most recent block.

  • oldest

    returns the oldest block available at the orderer for the channel. This may be a user transaction block or a configuration block.

    This option will also return the block number of the oldest available block.

  • config

    returns the most recent configuration block available at the orderer for the channel.

    This option will also return the block number of the most recent configuration block.

  • (block number)

    returns the requested block for the channel. This may be a user transaction block or a configuration block.

    Specifying 0 will result in the genesis block for this channel being returned (if it is still available to the network orderer).

  • <outputFile>

    specifies the name of the file where the fetched block is written. If <outputFile> is not specified, then the block is written to the local directory in a file named as follows:

    • <channelID>_newest.block
    • <channelID>_oldest.block
    • <channelID>_config.block
    • <channelID>_(block number).block

Fetch Flags

The peer channel fetch command has the following command specific flags:

  • -c, --channelID <string>

    required, where <string> is the name of the channel for which the blocks are to be fetched from the orderer.

The global peer command flags also apply:

  • -o, --orderer required
  • --cafile optional
  • --certfile optional
  • --clientuth optional
  • --keyfile optional
  • --ordererTLSHostnameOverride optional
  • --tls optional

Fetch Usage

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.

    peer channel fetch newest mychannel.block -c mychannel --orderer orderer.example.com:7050

2018-02-25 13:10:16.137 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
2018-02-25 13:10:16.144 UTC [channelCmd] readBlock -> DEBU 00a Received block: 32
2018-02-25 13:10:16.145 UTC [main] main -> INFO 00b Exiting.....

ls -l

-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.

    peer channel fetch 16  -c mychannel --orderer orderer.example.com:7050

2018-02-25 13:46:50.296 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
2018-02-25 13:46:50.302 UTC [channelCmd] readBlock -> DEBU 00a Received block: 16
2018-02-25 13:46:50.302 UTC [main] main -> INFO 00b Exiting.....

ls -l

-rw-r--r-- 1 root root 11982 Feb 25 13:10 mychannel.block
-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

GetInfo Description

The peer channel getinfo command allows administrators to retrieve information about the peer's local blockchain for a particular channel. This includes the current blockchain height, and the hashes of the current block and previous block. Remember that a peer can be joined to more than one channel.

This information can be useful when administrators need to understand the current state of a peer's blockchain, especially in comparison to other peers in the same channel.

GetInfo Syntax

The peer channel getinfo command has the following syntax:

peer channel getinfo [flags]

GetInfo Flags

The peer channel getinfo command has no specific flags.

None of the global peer command flags apply, since this command does not interact with an orderer.

GetInfo Usage

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

  • Get information about the local peer for channel mychannel.

    peer channel getinfo -c mychannel

2018-02-25 15:15:44.135 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
Blockchain info: {"height":5,"currentBlockHash":"JgK9lcaPUNmFb5Mp1qe1SVMsx3o/22Ct4+n5tejcXCw=","previousBlockHash":"f8lZXoAn3gF86zrFq7L1DzW2aKuabH9Ow6SIE5Y04a4="}
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 crytographic hashes for the most recent blocks in the channel's blockchain.

peer channel join

Join Description

The peer channel join command allows administrators to join a peer to an existing channel. The administrator achieves this by using the command to provide a channel genesis block to the peer. The peer will then automatically retrieve the channel's blocks from other peers in the network, or the orderer, depending on the configuration, and the availability of other peers.

The administrator can create a local genesis block for use by this command by retrieving block 0 from an existing channel using the peer channel fetch command option. The peer channel create command will also return a local genesis block when a new channel is created.

Join Syntax

The peer channel join command has the following syntax:

peer channel join [flags]

Join Flags

The peer channel join command has the following command specific flags:

  • -b, --blockpath <string>

required, where <string> identifies a file containing the channel genesis block. This block can be retrieved using the peer channel fetch command, requesting block 0 from the channel, or using the peer channel create command.

None of the global peer command flags apply, since this command does not interact with an orderer.

Join Usage

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.

    peer channel join -b ./mychannel.genesis.block

2018-02-25 12:25:26.511 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
2018-02-25 12:25:26.571 UTC [channelCmd] executeJoin -> INFO 006 Successfully submitted proposal to join channel
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 list

List Description

The peer channel list command allows administrators list the channels to which a peer is joined.

List Syntax

The peer channel list command has the following syntax:

peer channel list [flags]

List Flags

The peer channel list command has no specific flags.

None of the global peer command flags apply, since this command does not interact with an orderer.

List Usage

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

  • List the channels to which a peer is joined.

    peer channel list

2018-02-25 14:21:20.361 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
Channels peers has joined:
mychannel
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

SignConfigTx Description

The peer channel signconfigtx command helps administrators sign a configuration transaction with the peer's identity credentials prior to submission to an orderer. Typical configuration transactions include creating a channel or updating a channel configuration.

The administrator supplies an input file to the signconfigtx command which describes the configuration transaction. The command then adds the peer's public identity to the file, and signs the entire payload with the peer's private key. The command uses the peer's public and private credentials stored in its local MSP. A new file is not generated; the input file is updated in place.

signconfigtx only signs the configuration transaction; it does not create it, nor submit it to the orderer. Typically, the configuration transaction has been already created using the configtxgen command, and is subsequently submitted to the orderer by an appropriate command such as peer channel update.

SignConfigTx Syntax

The peer channel signconfigtx command has the following syntax:

peer channel signconfigtx [flags]

SignConfigTx Flags

The peer channel signconfigtx command has the following command specific flags:

  • -f, --file <string>

required, where <string> identifies a file containing the channel configuration transaction to be signed on behalf of the peer.

None of the global peer command flags apply, since this command does not interact with an orderer.

SignConfigTx Usage

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

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

    ls -l

-rw-r--r--  1 anthonyodowd  staff   284 25 Feb 18:16 updatechannel.tx

peer channel signconfigtx -f updatechannel.tx

2018-02-25 18:16:44.456 GMT [channelCmd] InitCmdFactory -> INFO 001 Endorser and orderer connections initialized
2018-02-25 18:16:44.459 GMT [main] main -> INFO 002 Exiting.....

ls -l

-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

Update Description

The peer channel update command allows administrators to update an existing channel.

To update a channel, the administrator uses the command to submit a configuration transaction to the orderer which describes the required channel configuration changes. This transaction must be signed by the required organizations as defined in the current channel configuration. Configuration transactions can be generated by the configtxgen command and signed by the peer channel signconfigtx command.

The update transaction is sent by the command to the orderer, which validates the change is authorized, and then distributes a configuration block to every peer on the channel. In this way, every peer on the channel maintains a consistent copy of the channel configuration.

Update Syntax

The peer channel update command has the following syntax:

peer channel update [flags]

Update flags

The peer channel update command has the following command specific flags:

  • -c, --channelID <string>

    required, where <string> is the name of the channel which is to be updated.

  • -f, --file <string>

    required, where <string> identifies a transaction configuration file. This file contains the configuration change required to this channel, and it can be generated by configtxgen command.

The global peer command flags also apply as follows:

  • -o, --orderer required
  • --cafile optional
  • --certfile optional
  • --clientuth optional
  • --keyfile optional
  • --ordererTLSHostnameOverride optional
  • --tls optional

Update Usage

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

  • Update the channel mychannel using the configuration transaction defined in the file ./updatechannel.txn. 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.

    peer channel update -c mychannel -f ./updatechannel.txn -o orderer.example.com:7050

2018-02-23 06:32:11.569 UTC [channelCmd] InitCmdFactory -> INFO 003 Endorser and orderer connections initialized
2018-02-23 06:32:11.626 UTC [main] main -> INFO 010 Exiting.....

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