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 atorderer.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 byconfigtxgen
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 addressorderer.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 asmychannel.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 filemychannel.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 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 thepeer 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 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 byconfigtxgen
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 addressorderer.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.