osnadmin CLI command reference #2077
Conversation
There was a problem hiding this comment.
@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
| Path to the file containing the config block | ||
| ``` |
There was a problem hiding this comment.
To be more specific, should this say Path to the file containing the channel genesis block or the latest config block?
| 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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
I can certainly add that if you think it'd be beneficial.
| -o, --orderer-address=ORDERER-ADDRESS | ||
| Endpoint of the OSN |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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).
| --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 |
There was a problem hiding this comment.
How do they know that these 2 fields are required and not optional throughout these commands?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Updated to Path to file containing PEM-encoded TLS CA certificate(s) for the OSN
Added it to the command_ref. |
cmd/osnadmin/main.go
Outdated
| @@ -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() | |||
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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"?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Done. Switched to "up-to-date config block".
wlahti
force-pushed
the
fab-18309
branch
4 times, most recently
from
3fb6e0a
to
93d718b
Compare
FAB-18309 #done Signed-off-by: Will Lahti <wtlahti@us.ibm.com>
|
Rebased and updated the reference doc for the rename of |
Type of change
Description
Command reference documentation for the osnadmin CLI.
Related issues
FAB-18309