osnadmin CLI command reference #2077

wlahti · 2020-11-05T19:11:11Z

Type of change

Documentation update

Description

Command reference documentation for the osnadmin CLI.

Related issues

pamandrejko

@wlahti There's something missing here because the command is not showing up in the rendered content:
https://hyperledger-fabric--2077.org.readthedocs.build/en/2077/command_ref.html

pamandrejko

A few questions

pamandrejko · 2020-11-05T19:59:00Z

docs/source/commands/osnadminchannel.md

+                                 Path to the file containing the config block
+```


To be more specific, should this say Path to the file containing the channel genesis block or the latest config block?

pamandrejko · 2020-11-05T20:04:17Z

docs/wrappers/osnadmin_channel_preamble.md

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


Would it be appropriate to mention here that the join and remove commands cannot be used if the ordering node is part of a system channel?

I can certainly add that if you think it'd be beneficial.

pamandrejko · 2020-11-05T20:05:08Z

docs/source/commands/osnadminchannel.md

+  -o, --orderer-address=ORDERER-ADDRESS  
+                                 Endpoint of the OSN


I am not sure what ORDERER-ADDRESS is meant to refer to. Should this be --orderer-address=ORDERER-ADMIN-LISTENADDRESS?
and instead of Endpoint of the OSN, it should Admin endpoint of the OSN?

I can clarify that it's the Admin endpoint of the OSN but the ORDERER-ADDRESS part is just how the CLI library we're using prints that info (I can't change it unless we also change the name of the flag).

pamandrejko · 2020-11-05T20:33:15Z

docs/source/commands/osnadminchannel.md

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


How do they know that these 2 fields are required and not optional throughout these commands?

The flags are all set as required in the implementation (the only optional flag for any the commands is --channel-id on the list command). The CLI will return an error if any required flags are not set. Do we do anything to differentiate the required flags for other commands that you're aware of?

OK makes sense. Then I would suggest we update the list command so they know that --channel-id is optional -- if not specified they will get back the details of all the channels the osn is a member of instead of a specific one.

I have that included in the description for list: "If the channel-id flag is set, more detailed information will be provided for that channel." and also mention it in the example usage for the command.

Do you have specific places you'd like to see more added?

For the --ca-file flag, how would they know this is the root cert of the TLS CA and not the organization CA?
Should it be:
Path to file containing PEM-encoded trusted TLS certificate(s) for the OSN
or more specifically:
Path to file containing PEM-encoded trusted root certificate(s) of the TLS CA for the OSN

I reused the flag description that we've been using for years on the peer channel flag of the same name. I can certainly update this if we think it's beneficial.

Updated to Path to file containing PEM-encoded TLS CA certificate(s) for the OSN

wlahti · 2020-11-05T20:51:54Z

@wlahti There's something missing here because the command is not showing up in the rendered content:
https://hyperledger-fabric--2077.org.readthedocs.build/en/2077/command_ref.html

Added it to the command_ref.

jyellick

Mostly looks good to me

jyellick · 2020-11-06T21:09:31Z

cmd/osnadmin/main.go

@@ -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 the config block. This can be either the genesis block or a config block for the channel.").Short('b').Required().String()


Is this to address another comment? The genesis block is a config block, it's just the first one. Really, this should be the latest config block, or, a config block which contains the current set consenters and corresponding TLS CAs (as required to replicate the channel).

Not sure how much we can/should bake into a one/two-liner. Maybe switch back towards the original text with a minor clarification: "Path to the file containing a config block for the channel"?

Perhaps something like: "Path to the file containing an up to date config block for the channel."? Maybe that creates more confusion than clarity. My biggest concern was that adding the longer statement about genesis or config was verbose without adding info.

Done. Switched to "up-to-date config block".

FAB-18309 #done Signed-off-by: Will Lahti <wtlahti@us.ibm.com>

wlahti · 2020-11-09T18:42:28Z

Rebased and updated the reference doc for the rename of clusterRelation to consensusRelation.

wlahti requested review from a team as code owners November 5, 2020 19:11

pamandrejko reviewed Nov 5, 2020

View reviewed changes

wlahti force-pushed the fab-18309 branch from 015731b to 266adad Compare November 5, 2020 20:51

wlahti force-pushed the fab-18309 branch from 266adad to fd8f5a6 Compare November 6, 2020 12:46

pamandrejko mentioned this pull request Nov 6, 2020

[FAB-18179] Channel Participation API tutorial #2081

Merged

denyeart added the channel-participation-api label Nov 6, 2020

jyellick reviewed Nov 6, 2020

View reviewed changes

wlahti force-pushed the fab-18309 branch 4 times, most recently from 3fb6e0a to 93d718b Compare November 9, 2020 18:03

jyellick previously approved these changes Nov 9, 2020

View reviewed changes

osnadmin command reference

7461d63

FAB-18309 #done Signed-off-by: Will Lahti <wtlahti@us.ibm.com>

wlahti dismissed jyellick’s stale review via 7461d63 November 9, 2020 18:36

wlahti force-pushed the fab-18309 branch from 93d718b to 7461d63 Compare November 9, 2020 18:36

jyellick approved these changes Nov 9, 2020

View reviewed changes

jyellick merged commit 1e90c88 into hyperledger:master Nov 9, 2020

pamandrejko mentioned this pull request Nov 15, 2020

[FAB-18179] Channel Participation API Tutorial #2127

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

osnadmin CLI command reference #2077

osnadmin CLI command reference #2077

wlahti commented Nov 5, 2020

pamandrejko left a comment

pamandrejko left a comment

pamandrejko Nov 5, 2020

wlahti Nov 5, 2020

pamandrejko Nov 5, 2020

wlahti Nov 5, 2020

wlahti Nov 5, 2020

pamandrejko Nov 5, 2020

wlahti Nov 5, 2020

wlahti Nov 5, 2020

pamandrejko Nov 5, 2020

wlahti Nov 5, 2020

pamandrejko Nov 5, 2020

wlahti Nov 6, 2020

pamandrejko Nov 6, 2020

wlahti Nov 9, 2020

wlahti Nov 9, 2020 •

edited

Loading

wlahti commented Nov 5, 2020

jyellick left a comment

jyellick Nov 6, 2020

wlahti Nov 6, 2020

jyellick Nov 9, 2020

wlahti Nov 9, 2020 •

edited

Loading

wlahti commented Nov 9, 2020

osnadmin CLI command reference #2077

osnadmin CLI command reference #2077

Conversation

wlahti commented Nov 5, 2020

Type of change

Description

Related issues

pamandrejko left a comment

Choose a reason for hiding this comment

pamandrejko left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wlahti Nov 9, 2020 • edited Loading

Choose a reason for hiding this comment

wlahti commented Nov 5, 2020

jyellick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wlahti Nov 9, 2020 • edited Loading

Choose a reason for hiding this comment

wlahti commented Nov 9, 2020

wlahti Nov 9, 2020 •

edited

Loading

wlahti Nov 9, 2020 •

edited

Loading