osnadmin command reference (#2077)

FAB-18309 #done Signed-off-by: Will Lahti <[email protected]>
hyperledger · Nov 9, 2020 · 1e90c88 · 1e90c88
1 parent 4b134cf
commit 1e90c88
Show file tree

Hide file tree

Showing 6 changed files with 330 additions and 3 deletions.
diff --git a/cmd/osnadmin/main.go b/cmd/osnadmin/main.go
@@ -41,16 +41,16 @@ 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()
 
 	channel := app.Command("channel", "Channel actions")
 
 	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
@@ -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
@@ -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 <command> [<args> ...]
+
+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 [<flags>]
+    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 [<flags>]
+
+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. 
+
+<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>.
diff --git a/docs/wrappers/osnadmin_channel_postscript.md 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. 
+
+<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>.
diff --git a/docs/wrappers/osnadmin_channel_preamble.md 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
@@ -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