From 1e90c8889448c79e402f06c84106c0ca89bbe731 Mon Sep 17 00:00:00 2001 From: Will Lahti Date: Mon, 9 Nov 2020 15:35:44 -0500 Subject: [PATCH] osnadmin command reference (#2077) FAB-18309 #done Signed-off-by: Will Lahti --- cmd/osnadmin/main.go | 6 +- docs/source/command_ref.rst | 1 + docs/source/commands/osnadminchannel.md | 214 +++++++++++++++++++ docs/wrappers/osnadmin_channel_postscript.md | 86 ++++++++ docs/wrappers/osnadmin_channel_preamble.md | 19 ++ scripts/generateHelpDocs.sh | 7 + 6 files changed, 330 insertions(+), 3 deletions(-) create mode 100644 docs/source/commands/osnadminchannel.md create mode 100644 docs/wrappers/osnadmin_channel_postscript.md create mode 100644 docs/wrappers/osnadmin_channel_preamble.md diff --git a/cmd/osnadmin/main.go b/cmd/osnadmin/main.go index c71aa5e55d5..c13b2775fea 100644 --- a/cmd/osnadmin/main.go +++ b/cmd/osnadmin/main.go @@ -41,8 +41,8 @@ func executeForArgs(args []string) (output string, exit int, err error) { // command line flags // app := kingpin.New("osnadmin", "Orderer Service Node (OSN) administration") - orderer := app.Flag("orderer-address", "Endpoint of the OSN").Short('o').Required().String() - caFile := app.Flag("ca-file", "Path to file containing PEM-encoded trusted certificate(s) for the OSN").Required().String() + orderer := app.Flag("orderer-address", "Admin endpoint of the OSN").Short('o').Required().String() + caFile := app.Flag("ca-file", "Path to file containing PEM-encoded TLS CA certificate(s) for the OSN").Required().String() clientCert := app.Flag("client-cert", "Path to file containing PEM-encoded X509 public key to use for mutual TLS communication with the OSN").Required().String() clientKey := app.Flag("client-key", "Path to file containing PEM-encoded private key to use for mutual TLS communication with the OSN").Required().String() @@ -50,7 +50,7 @@ func executeForArgs(args []string) (output string, exit int, err error) { join := channel.Command("join", "Join an Ordering Service Node (OSN) to a channel. If the channel does not yet exist, it will be created.") joinChannelID := join.Flag("channel-id", "Channel ID").Short('c').Required().String() - configBlockPath := join.Flag("config-block", "Path to the file containing the config block").Short('b').Required().String() + configBlockPath := join.Flag("config-block", "Path to the file containing an up-to-date config block for the channel").Short('b').Required().String() list := channel.Command("list", "List channel information for an Ordering Service Node (OSN). If the channel-id flag is set, more detailed information will be provided for that channel.") listChannelID := list.Flag("channel-id", "Channel ID").Short('c').String() diff --git a/docs/source/command_ref.rst b/docs/source/command_ref.rst index fca5108e303..59a348f64c9 100644 --- a/docs/source/command_ref.rst +++ b/docs/source/command_ref.rst @@ -11,6 +11,7 @@ Commands Reference commands/peersnapshot.md commands/peerversion.md commands/peernode.md + commands/osnadminchannel.md commands/configtxgen.md commands/configtxlator.md commands/cryptogen.md diff --git a/docs/source/commands/osnadminchannel.md b/docs/source/commands/osnadminchannel.md new file mode 100644 index 00000000000..31cef838872 --- /dev/null +++ b/docs/source/commands/osnadminchannel.md @@ -0,0 +1,214 @@ +# osnadmin channel + +The `osnadmin channel` command allows administrators to perform channel-related +operations on an orderer, such as joining a channel, listing the channels an +orderer has joined, and removing a channel. The channel participation API must +be enabled and the Admin endpoint must be configured in the `orderer.yaml` for +each orderer. + +*Note: For a network using a system channel, `list` (for all channels) and +`remove` (for the system channel) are the only supported operations. Any other +attempted operation will return an error. + +## Syntax + +The `osnadmin channel` command has the following subcommands: + + * join + * list + * remove + +## osnadmin channel +``` +usage: osnadmin channel [ ...] + +Channel actions + +Flags: + --help Show context-sensitive help (also try + --help-long and --help-man). + -o, --orderer-address=ORDERER-ADDRESS + Admin endpoint of the OSN + --ca-file=CA-FILE Path to file containing PEM-encoded TLS CA + certificate(s) for the OSN + --client-cert=CLIENT-CERT Path to file containing PEM-encoded X509 public + key to use for mutual TLS communication with + the OSN + --client-key=CLIENT-KEY Path to file containing PEM-encoded private key + to use for mutual TLS communication with the + OSN + +Subcommands: + channel join --channel-id=CHANNEL-ID --config-block=CONFIG-BLOCK + Join an Ordering Service Node (OSN) to a channel. If the channel does not + yet exist, it will be created. + + channel list [] + List channel information for an Ordering Service Node (OSN). If the + channel-id flag is set, more detailed information will be provided for that + channel. + + channel remove --channel-id=CHANNEL-ID + Remove an Ordering Service Node (OSN) from a channel. +``` + + +## osnadmin channel join +``` +usage: osnadmin channel join --channel-id=CHANNEL-ID --config-block=CONFIG-BLOCK + +Join an Ordering Service Node (OSN) to a channel. If the channel does not yet +exist, it will be created. + +Flags: + --help Show context-sensitive help (also try + --help-long and --help-man). + -o, --orderer-address=ORDERER-ADDRESS + Admin endpoint of the OSN + --ca-file=CA-FILE Path to file containing PEM-encoded TLS CA + certificate(s) for the OSN + --client-cert=CLIENT-CERT Path to file containing PEM-encoded X509 public + key to use for mutual TLS communication with + the OSN + --client-key=CLIENT-KEY Path to file containing PEM-encoded private key + to use for mutual TLS communication with the + OSN + -c, --channel-id=CHANNEL-ID Channel ID + -b, --config-block=CONFIG-BLOCK + Path to the file containing an up-to-date + config block for the channel +``` + + +## osnadmin channel list +``` +usage: osnadmin channel list [] + +List channel information for an Ordering Service Node (OSN). If the channel-id +flag is set, more detailed information will be provided for that channel. + +Flags: + --help Show context-sensitive help (also try + --help-long and --help-man). + -o, --orderer-address=ORDERER-ADDRESS + Admin endpoint of the OSN + --ca-file=CA-FILE Path to file containing PEM-encoded TLS CA + certificate(s) for the OSN + --client-cert=CLIENT-CERT Path to file containing PEM-encoded X509 public + key to use for mutual TLS communication with + the OSN + --client-key=CLIENT-KEY Path to file containing PEM-encoded private key + to use for mutual TLS communication with the + OSN + -c, --channel-id=CHANNEL-ID Channel ID +``` + + +## osnadmin channel remove +``` +usage: osnadmin channel remove --channel-id=CHANNEL-ID + +Remove an Ordering Service Node (OSN) from a channel. + +Flags: + --help Show context-sensitive help (also try + --help-long and --help-man). + -o, --orderer-address=ORDERER-ADDRESS + Admin endpoint of the OSN + --ca-file=CA-FILE Path to file containing PEM-encoded TLS CA + certificate(s) for the OSN + --client-cert=CLIENT-CERT Path to file containing PEM-encoded X509 public + key to use for mutual TLS communication with + the OSN + --client-key=CLIENT-KEY Path to file containing PEM-encoded private key + to use for mutual TLS communication with the + OSN + -c, --channel-id=CHANNEL-ID Channel ID +``` + +## Example Usage + +### osnadmin channel join examples + +Here's an example of the `osnadmin channel join` command. + +* Create and join a sample channel `mychannel` defined by the application channel genesis + block contained in file `mychannel-genesis-block.pb`. Use the orderer admin endpoint + at `orderer.example.com:9443`. + + ``` + + osnadmin channel join -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY --channel-id mychannel --config-block mychannel-genesis-block.pb + + Status: 201 + { + "name": "mychannel", + "url": "/participation/v1/channels/mychannel", + "consensusRelation": "consenter", + "status": "active", + "height": 1 + } + + ``` + + Status 201 and the channel details are returned indicating that the channel has been + successfully created and joined. + +### osnadmin channel list example + +Here are some examples of the `osnadmin channel list` command. + +* Listing all the channels that the orderer has joined. This includes the + system channel (if one exists) and all of the application channels. + + ``` + osnadmin channel list -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY + + Status: 200 + { + "systemChannel": null, + "channels": [ + { + "name": "mychannel", + "url": "/participation/v1/channels/mychannel" + } + ] + } + + ``` + + Status 200 and the list of channels are returned. + +* Using the `--channel-id` flag to list more details for `mychannel`. + + ``` + osnadmin channel list -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY --channel-id mychannel + + Status: 200 + { + "name": "mychannel", + "url": "/participation/v1/channels/mychannel", + "consensusRelation": "consenter", + "status": "active", + "height": 3 + } + + ``` + + Status 200 and the details of the channels are returned. + +### osnadmin channel remove example + +Here's an example of the `osnadmin channel remove` command. + +* Removing channel `mychannel` from the orderer at `orderer.example.com:9443`. + + ``` + osnadmin channel remove -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY --channel-id mychannel + + Status: 204 + ``` + + Status 204 is returned upon successful removal of a channel. + +Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License. diff --git a/docs/wrappers/osnadmin_channel_postscript.md b/docs/wrappers/osnadmin_channel_postscript.md new file mode 100644 index 00000000000..83a9436251e --- /dev/null +++ b/docs/wrappers/osnadmin_channel_postscript.md @@ -0,0 +1,86 @@ +## Example Usage + +### osnadmin channel join examples + +Here's an example of the `osnadmin channel join` command. + +* Create and join a sample channel `mychannel` defined by the application channel genesis + block contained in file `mychannel-genesis-block.pb`. Use the orderer admin endpoint + at `orderer.example.com:9443`. + + ``` + + osnadmin channel join -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY --channel-id mychannel --config-block mychannel-genesis-block.pb + + Status: 201 + { + "name": "mychannel", + "url": "/participation/v1/channels/mychannel", + "consensusRelation": "consenter", + "status": "active", + "height": 1 + } + + ``` + + Status 201 and the channel details are returned indicating that the channel has been + successfully created and joined. + +### osnadmin channel list example + +Here are some examples of the `osnadmin channel list` command. + +* Listing all the channels that the orderer has joined. This includes the + system channel (if one exists) and all of the application channels. + + ``` + osnadmin channel list -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY + + Status: 200 + { + "systemChannel": null, + "channels": [ + { + "name": "mychannel", + "url": "/participation/v1/channels/mychannel" + } + ] + } + + ``` + + Status 200 and the list of channels are returned. + +* Using the `--channel-id` flag to list more details for `mychannel`. + + ``` + osnadmin channel list -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY --channel-id mychannel + + Status: 200 + { + "name": "mychannel", + "url": "/participation/v1/channels/mychannel", + "consensusRelation": "consenter", + "status": "active", + "height": 3 + } + + ``` + + Status 200 and the details of the channels are returned. + +### osnadmin channel remove example + +Here's an example of the `osnadmin channel remove` command. + +* Removing channel `mychannel` from the orderer at `orderer.example.com:9443`. + + ``` + osnadmin channel remove -o orderer.example.com:9443 --ca-file $CA_FILE --client-cert $CLIENT_CERT --client-key $CLIENT_KEY --channel-id mychannel + + Status: 204 + ``` + + Status 204 is returned upon successful removal of a channel. + +Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License. diff --git a/docs/wrappers/osnadmin_channel_preamble.md b/docs/wrappers/osnadmin_channel_preamble.md new file mode 100644 index 00000000000..131584faa61 --- /dev/null +++ b/docs/wrappers/osnadmin_channel_preamble.md @@ -0,0 +1,19 @@ +# osnadmin channel + +The `osnadmin channel` command allows administrators to perform channel-related +operations on an orderer, such as joining a channel, listing the channels an +orderer has joined, and removing a channel. The channel participation API must +be enabled and the Admin endpoint must be configured in the `orderer.yaml` for +each orderer. + +*Note: For a network using a system channel, `list` (for all channels) and +`remove` (for the system channel) are the only supported operations. Any other +attempted operation will return an error. + +## Syntax + +The `osnadmin channel` command has the following subcommands: + + * join + * list + * remove diff --git a/scripts/generateHelpDocs.sh b/scripts/generateHelpDocs.sh index 6c88d80ce82..e2da4cf58a5 100755 --- a/scripts/generateHelpDocs.sh +++ b/scripts/generateHelpDocs.sh @@ -100,4 +100,11 @@ generateHelpText \ docs/wrappers/configtxlator_postscript.md \ "${commands[@]}" +commands=("osnadmin channel" "osnadmin channel join" "osnadmin channel list" "osnadmin channel remove") +generateHelpText \ + docs/source/commands/osnadminchannel.md \ + docs/wrappers/osnadmin_channel_preamble.md \ + docs/wrappers/osnadmin_channel_postscript.md \ + "${commands[@]}" + exit