Update FeatureUtility command to include new verify option

[jjiwooLim]

Epic: OpenLiberty/open-liberty#17220

• The FeatureUtility installFeature and installServerFeatures commands need to be updated with the new verify option.

Option

Description

--verify = verify_option

Specifies how features should be verified. Supported values are enforce,skip,all, and warn. If this option isn't specified, a default value of enforce is used. - enforce: Verifies the signatures of all Liberty features except for user features. - skip: Skips verification altogether and does not download any feature signatures. - all: Verifies both Liberty features and user features. - warn: Same as "all", but it will not terminate installation in the event that verification fails.

• Add new properties under "Modifications for featureUtility commands" (https://openliberty.io/docs/latest/reference/command/featureUtility-commands.html)

Environment variable	Corresponding properties	Description
FEATURE_VERIFY	feature.verify	Same as setting --verify option for installFeature and installServerFeatures command.

• Add new subject header "Verify user features"

You can verify your user features by providing your public key ID and key URL. Instructions on generating a key pair, signing the user feature and distributing your key can be found here.

#Provide long key ID (64 bit) format
myKey.keyid=0xBD9FD5BE9E68CA00

#Provide full URL of your key
myKey.keyurl=https://keyserver.ubuntu.com/pks/lookup?op=get&options=mr&search=0xBD9FD5BE9E68CA00

#It can also be local file 
# myKey.keyurl=/pubkey.asc

[ramkumar-k-9286]

@jjiwooLim

Hi Sarah,

The suggested changes have been made to the documentation.

Draft links:

1. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installFeature.html
2. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installServerFeatures.html
3. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-commands.html

Please review the changes.
If they are as per expectation, please add the Developer Reviewed label.

Regards,
Ramkumar

CC @dmuelle

[ramkumar-k-9286]

@dmuelle

Hi David

Please Peer Review the changes made based on this issue.

Draft links:

1. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installFeature.html
2. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installServerFeatures.html
3. https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-commands.html

Regards,
Ramkumar

[dmuelle]

Hi Ram, just a few minor suggestions

• i think it should be more clear that verify_option is an example variable that is replaced with one of the four values It should render in italics like other variable examples on this page
• If this option is not specified, a default value encode is used.---> If this option is not specified, the default value is encode .
• for warn, does failure result in a warning message to the console? The name suggests this but the description doesn't say
• in the table on this page, replace this description with a description of what it actually does: "Same as setting --verify option for installFeature and installServerFeatures command."
• under "verify use features" separate the code comments from the examples, and rewrite the last description to be more concrete: "It can also be local file"

[ramkumar-k-9286]

@jjiwooLim

Hi Sarah,

Incorporated David's Peer Review comments. Could you have a look at David's comments as well as my changes and suggest modifications, if any?

Draft links:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installFeature.html
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installServerFeatures.html
https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-commands.html

Regards,
Ramkumar

CC @dmuelle

[jjiwooLim]

Hi @ramkumar-k-9286 ,

I reviewed again after reading David's comment.

• - verify_option is still not rendered as italics in both installFeature and installServerFeatures page.

• - All 3 pages have slightly different descriptions for enforce, skip, all, and warn. Should we be consistent? I think the descriptions on featureUtility-command page is the most descriptive ones.

• - for warn it does result in a warning message to the console. We should mention it.
  eg) "A verification failure does not immediately end the installation process, but it will result in a warning message. "

• - under "verify use features", it might be worth mentioning the supported protocols for key URL.
  "Supported protocols are HTTP, HTTPS, and file."

• I forgot that we introduced a new exit code for the FeatureUtility installFeature and installServerFeatures commands. Exit code 37 is added.

| Code | Explanation |
| 37 | 37 indicates that the feature signature verification failed. |

[ramkumar-k-9286]

@jjiwooLim

Hi Sarah,

Incorporated your review comments. Could you have a look at the changes and see if you are ok with the modifications.

Draft links:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installFeature.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installServerFeatures.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-commands.html

Regards,
Ramkumar

CC @dmuelle

[jjiwooLim]

lgtm!

[dmuelle]

LGTM, thanks

[dmuelle]

Epic moved to 23.0.0.8

[ramkumar-k-9286]

Hi David @dmuelle

Draft links on draft.

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installFeature.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installServerFeatures.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-commands.html

Regards,
Ramkumar

[dmuelle]

LGTM, send to staging when you have a chance

[jjiwooLim]

@ramkumar-k-9286 @dmuelle Sorry this is moved to 23.0.0.10.

[dmuelle]

Thanks @jjiwooLim - in that case @ramkumar-k-9286 , we can just leave it as is in draft until the feature is ready to release.

[jjiwooLim]

Typo found: --verify = encode should be enforce

Specifies how features must be verified. how features should be verified during a process or installation. Supported values are enforce, skip, all, and warn. If this option is not specified, the default value is enforce.

enforce: Verifies the signatures of all Liberty features except for user features. It checks the integrity and authenticity of the features that are provided by the Liberty framework.

[ramkumar-k-9286]

Hi,

@jjiwooLim @dmuelle @lauracowen

Corrections done: encode has been replaced with enforce.

Corrected one other mistake @lauracowen pointed out: Specifies how features must be verified during a process or an installation.

Draft links:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installFeature.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-installServerFeatures.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/command/featureUtility-commands.html

Regards,
Ramkumar

[jjiwooLim]

I don't see this update in the https://openliberty.io/docs/latest/reference/command/featureUtility-modifications.html

[dmuelle]

Hi @jjiwooLim - that information was moved to https://openliberty.io/docs/latest/reference/command/featureUtility-commands.html#_modifications_for_featureutility_commands

The link you found was an artifact that needs to be deleted. Apparently the page was removed from the TOC but the file was not deleted. I will delete it in the next doc release to ensure it can't be found by accident. Thanks