peerchannel.md 18.9 KB
Newer Older
1
# peer channel
2
3
4
5
6
7
8

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

9
10
11
12
13
14
15
16
17
The `peer channel` command has the following subcommands:

  * create
  * fetch
  * getinfo
  * join
  * list
  * signconfigtx
  * update
18

19
## peer channel
20
```
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
Operate a channel: create|fetch|join|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.

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
  -h, --help                                help for channel
      --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

Global Flags:
      --logging-level string   Default logging level and overrides, see core.yaml for full syntax

Use "peer channel [command] --help" for more information about a command.
49
50
51
```


52
## peer channel create
53
```
54
Create a channel and write the genesis block to a file.
55
56
57
58
59

Usage:
  peer channel create [flags]

Flags:
pama-ibm's avatar
pama-ibm committed
60
  -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.-]*
61
62
63
64
  -f, --file string          Configuration transaction file generated by a tool such as configtxgen for submitting to orderer
  -h, --help                 help for create
      --outputBlock string   The path to write the genesis block for the channel. (default ./<channelID>.block)
  -t, --timeout int          Channel creation timeout (default 5)
65
66
67
68
69
70
71
72
73
74
75

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
76
77


78
## peer channel fetch
79
80
81
82
83
84
85
```
Fetch a specified block, writing it to a file.

Usage:
  peer channel fetch <newest|oldest|config|(number)> [outputfile] [flags]

Flags:
pama-ibm's avatar
pama-ibm committed
86
  -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.-]*
87
88
89
90
91
92
93
94
95
96
97
98
  -h, --help               help for fetch

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
99
100


101
## peer channel getinfo
102
103
104
105
106
107
108
```
get blockchain information of a specified channel. Requires '-c'.

Usage:
  peer channel getinfo [flags]

Flags:
pama-ibm's avatar
pama-ibm committed
109
  -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.-]*
110
111
112
113
114
115
116
117
118
119
120
121
  -h, --help               help for getinfo

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
122
123


124
## peer channel join
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
```
Joins the peer to a channel.

Usage:
  peer channel join [flags]

Flags:
  -b, --blockpath string   Path to file containing genesis block
  -h, --help               help for join

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
145
146


147
## peer channel list
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
```
List of channels peer has joined.

Usage:
  peer channel list [flags]

Flags:
  -h, --help   help for list

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
167
168


169
## peer channel signconfigtx
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
```
Signs the supplied configtx update file in place on the filesystem. Requires '-f'.

Usage:
  peer channel signconfigtx [flags]

Flags:
  -f, --file string   Configuration transaction file generated by a tool such as configtxgen for submitting to orderer
  -h, --help          help for signconfigtx

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
190
191


192
## peer channel update
193
194
195
196
197
198
199
```
Signs and sends the supplied configtx update file to the channel. Requires '-f', '-o', '-c'.

Usage:
  peer channel update [flags]

Flags:
pama-ibm's avatar
pama-ibm committed
200
  -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.-]*
201
202
203
204
205
206
207
208
209
210
211
212
213
  -f, --file string        Configuration transaction file generated by a tool such as configtxgen for submitting to orderer
  -h, --help               help for update

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
      --keyfile string                      Path to file containing PEM-encoded private key to use for mutual TLS communication with the orderer endpoint
      --logging-level string                Default logging level and overrides, see core.yaml for full syntax
  -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
```
214

215
## Example Usage
216

217
### peer channel create examples
218
219
220
221
222
223
224
225
226
227
228
229

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
230
  2018-02-25 08:23:57.834 UTC [channelCmd] readBlock -> INFO 020 Received block: 0
231
232
233
234
235
236
237
238
239
240
241
242
243
244
  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.txn`.
  Wait 30 seconds for the channel to be created.

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

247
248
    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
249
    2018-02-23 06:31:58.877 UTC [channelCmd] readBlock -> INFO 020 Received block: 0
250
    2018-02-23 06:31:58.878 UTC [main] main -> INFO 021 Exiting.....
251

252
    ls -l
253

254
    -rw-r--r-- 1 root root 11982 Feb 25 12:24 mychannel.block
255
256
257
258
259
260
261
262
263
264
265
266
267

  ```

  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.

268
### peer channel fetch example
269

270
Here's some examples of the `peer channel fetch` command.
271

272
273
* Using the `newest` option to retrieve the most recent channel block, and
  store it in   the file `mychannel.block`.
274

275
276
  ```
  peer channel fetch newest mychannel.block -c mychannel --orderer orderer.example.com:7050
277

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

282
  ls -l
283

284
  -rw-r--r-- 1 root root 11982 Feb 25 13:10 mychannel.block
285

286
  ```
287

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

291
292
* Using the `(block number)` option to retrieve a specific block -- in this
  case, block number 16 -- and store it in the default block file.
293

294
295
  ```
  peer channel fetch 16  -c mychannel --orderer orderer.example.com:7050
296

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

301
  ls -l
302

303
304
  -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
305

306
  ```
307

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

311
312
313
314
  For configuration blocks, the block file can be decoded using the
  [`configtxlator` command](./configtxlator.html). 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.
315

316
### peer channel getinfo example
317
318
319
320
321
322
323
324
325
326
327
328
329
330

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

  ```

331
332
333
  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.
334

335
### peer channel join example
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353

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.

354
### peer channel list example
355

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

358
  * List the channels to which a peer is joined.
359

360
361
    ```
    peer channel list
362

363
364
365
366
    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.....
367

368
    ```
369

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

372
### peer channel signconfigtx example
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396

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
397
398
  transaction by the increase in the size of the file `updatechannel.tx` from
  284 bytes to 2180 bytes.
399

400
### peer channel update example
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417

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

<a rel="license" href="http://creativecommons.org/licenses/by/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.