osnadmin CLI command reference

[wlahti]

Type of change

• Documentation update

Description

Command reference documentation for the osnadmin CLI.

Related issues

FAB-18309

[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]

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

[wlahti]

Updated

[pamandrejko]

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?

[wlahti]

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

[wlahti]

Updated

[pamandrejko]

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?

[wlahti]

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

[wlahti]

Updated

[pamandrejko]

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

[wlahti]

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?

[pamandrejko]

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.

[wlahti]

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?

[pamandrejko]

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

[wlahti]

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.

[wlahti]

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

[wlahti]

@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]

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

[wlahti]

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"?

[jyellick]

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.

[wlahti]

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

[wlahti]

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