[
https://issues.apache.org/jira/browse/HDDS-15420?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Wei-Chiu Chuang updated HDDS-15420:
-----------------------------------
Description:
The Ozone command help menu is outdated, and can use some help.
{noformat}
$ /opt/ozone/bin/ozone
Usage: ozone [OPTIONS] SUBCOMMAND [SUBCOMMAND OPTIONS] OPTIONS is none or any
of:--buildpaths attempt to add class files from build tree
--config dir Ozone config directory
--daemon (start|status|stop) operate on a daemon
--debug turn on shell script debug mode
--help usage information
--hostnames list[,of,host,names] hosts to use in worker mode
--hosts filename list of hosts to use in worker mode
--jvmargs arguments append JVM options to any existing options
defined in the OZONE_OPTS environment variable. Any defined in
OZONE_CLIENT_OPTS will be append after these
jvmargs
--loglevel level set the log4j level for this command
--validate (continue) validates if all jars as indicated in the
corresponding OZONE_RUN_ARTIFACT_NAME classpath file are present, command
execution shall continue post validation
failure if 'continue' is passed
--workers turn on worker mode SUBCOMMAND is one of:
Admin Commands:daemonlog get/set the log level for each daemon Client
Commands:admin Ozone admin tool
classpath prints the class path needed for running ozone commands
completion generate autocompletion script for bash/zsh
debug Ozone debug tool
dtutil operations related to delegation tokens
envvars display computed Hadoop environment variables
freon runs an ozone data generator
fs run a filesystem command on Ozone file system. Equivalent to
'hadoop fs'
genconf generate minimally required ozone configs and output to
ozone-site.xml in specified path
getconf get ozone config values from configuration
insight tool to get runtime operation information
ratis Ozone ratis tool
repair Ozone repair tool
s3 command line interface for s3 related operations
sh command line interface for object store operations
tenant command line interface for multi-tenant related operations
version print the version Daemon Commands:csi run the
standalone CSI daemon
datanode run a HDDS datanode
httpfs run the HTTPFS compatible REST gateway
om Ozone Manager
recon run the Recon service
s3g run the S3 compatible REST gateway
scm run the Storage Container Manager serviceSUBCOMMAND may print help
when invoked w/o parameters or with -h. {noformat}
Here's the suggested change:
{noformat}
Based on a deep-dive review of the Apache Ozone shell entrypoint script (
ozone ), its helper library ( ozone-functions.sh ), and the Java auto-
completion
generation tools ( AutoCompletion.java ), here is the comprehensive analysis
of incorrect, missing, confusing, and outdated items in the provided help
message.
──────
### 1. Missing Subcommands
There are two fully implemented and supported Client Commands in the ozone
script that are completely missing from the help message:
• interactive : An interactive shell for Ozone commands.
• Registration in code: ozone_add_subcommand "interactive" client
"interactive shell for ozone commands"
• vapor : An Ozone server simulator (often used for benchmarks and
high-throughput generator simulation).
• Registration in code: ozone_add_subcommand "vapor" client "Ozone
server simulator"
──────
### 2. Missing Aliases & Undocumented Deprecated Commands
• shell (Alias): In the entrypoint script, the command shell is accepted
as an alias/synonym for sh (refer to sh | shell) inside the subcommand
case handler). It is fully supported but undocumented in the help list.
• auditparser (Deprecated): This legacy command is deprecated and no longer
documented. If executed, it outputs a warning and automatically redirects
to ozone debug auditparser :
warning: 'ozone auditparser' is deprecated, use 'ozone debug auditparser'
instead.
• checknative (Deprecated): Similar to auditparser , this is a legacy
command that is accepted with a deprecation warning and automatically rerouted
to ozone debug checknative :
warning: 'ozone checknative' is deprecated, use 'ozone debug checknative'
instead.
──────
### 3. Typographical and Grammatical Errors
• --jvmargs Option Typo:
• Help Text: "...Any defined in OZONE_CLIENT_OPTS will be append after
these jvmargs"
• Fix: Change append to appended (e.g., "...will be appended after
these jvmargs" ).
• --validate (continue) Option Clutter:
• Help Text: "...as indicated in the corresponding
OZONE_RUN_ARTIFACT_NAME classpath file..."
• Fix: Reference to the internal developer variable
OZONE_RUN_ARTIFACT_NAME is leaky and confusing for normal users. It should be
simplified to
describe that it validates the classpath jars.
──────
### 4. ⚠️ Developer Code Bug (Discovered in AutoCompletion.java )
There is a major description discrepancy inside the Java class
AutoCompletion.java which is used to generate the bash/zsh shell
auto-completion
scripts.
In
/hadoop-ozone/tools/src/main/java/org/apache/hadoop/ozone/utils/AutoCompletion.java
(lines 141–143):
@Option(names = {"--daemon"},
description = "attempt to add class files from build tree")
private String daemon;
• The Bug: The description for the --daemon option was accidentally
copy-pasted from the --buildpaths option ( "attempt to add class files from
build tree" ).
• The Correct Behavior: It should be "operate on a daemon" (accepting
start|status|stop ). As a result, the auto-completion scripts generated via
ozone completion will provide incorrect helper text for --daemon .
──────
### 5. Confusing / Outdated Design
• --validate (continue) Syntax:
• The help message formats this as --validate (continue) . The
parenthesis notation is ambiguous. It's not clear to an end-user whether they
should type --validate continue or --validate (continue) literally.
• A clearer representation would be --validate [continue] .
• csi Daemon Command:
• The csi (Container Storage Interface) daemon command is still listed
under Daemon Commands. In recent Kubernetes and container orchestration
setups, Ozone integrates through modern standard CSI plugins, making this
standalone CSI daemon command mostly legacy or obsolete for most
production deployments.
{noformat}
Also the 'ozone envvars' command should refer to "Ozone" instead of "Hadoop"
was:
The Ozone command help menu is outdated, and can use some help.
{noformat}
$ /opt/ozone/bin/ozone
Usage: ozone [OPTIONS] SUBCOMMAND [SUBCOMMAND OPTIONS] OPTIONS is none or any
of:--buildpaths attempt to add class files from build tree
--config dir Ozone config directory
--daemon (start|status|stop) operate on a daemon
--debug turn on shell script debug mode
--help usage information
--hostnames list[,of,host,names] hosts to use in worker mode
--hosts filename list of hosts to use in worker mode
--jvmargs arguments append JVM options to any existing options
defined in the OZONE_OPTS environment variable. Any defined in
OZONE_CLIENT_OPTS will be append after these
jvmargs
--loglevel level set the log4j level for this command
--validate (continue) validates if all jars as indicated in the
corresponding OZONE_RUN_ARTIFACT_NAME classpath file are present, command
execution shall continue post validation
failure if 'continue' is passed
--workers turn on worker mode SUBCOMMAND is one of:
Admin Commands:daemonlog get/set the log level for each daemon Client
Commands:admin Ozone admin tool
classpath prints the class path needed for running ozone commands
completion generate autocompletion script for bash/zsh
debug Ozone debug tool
dtutil operations related to delegation tokens
envvars display computed Hadoop environment variables
freon runs an ozone data generator
fs run a filesystem command on Ozone file system. Equivalent to
'hadoop fs'
genconf generate minimally required ozone configs and output to
ozone-site.xml in specified path
getconf get ozone config values from configuration
insight tool to get runtime operation information
ratis Ozone ratis tool
repair Ozone repair tool
s3 command line interface for s3 related operations
sh command line interface for object store operations
tenant command line interface for multi-tenant related operations
version print the version Daemon Commands:csi run the
standalone CSI daemon
datanode run a HDDS datanode
httpfs run the HTTPFS compatible REST gateway
om Ozone Manager
recon run the Recon service
s3g run the S3 compatible REST gateway
scm run the Storage Container Manager serviceSUBCOMMAND may print help
when invoked w/o parameters or with -h. {noformat}
Here's the suggested change:
{noformat}
Based on a deep-dive review of the Apache Ozone shell entrypoint script (
ozone ), its helper library ( ozone-functions.sh ), and the Java auto-
completion
generation tools ( AutoCompletion.java ), here is the comprehensive analysis
of incorrect, missing, confusing, and outdated items in the provided help
message.
──────
### 1. Missing Subcommands
There are two fully implemented and supported Client Commands in the ozone
script that are completely missing from the help message:
• interactive : An interactive shell for Ozone commands.
• Registration in code: ozone_add_subcommand "interactive" client
"interactive shell for ozone commands"
• vapor : An Ozone server simulator (often used for benchmarks and
high-throughput generator simulation).
• Registration in code: ozone_add_subcommand "vapor" client "Ozone
server simulator"
──────
### 2. Missing Aliases & Undocumented Deprecated Commands
• shell (Alias): In the entrypoint script, the command shell is accepted
as an alias/synonym for sh (refer to sh | shell) inside the subcommand
case handler). It is fully supported but undocumented in the help list.
• auditparser (Deprecated): This legacy command is deprecated and no longer
documented. If executed, it outputs a warning and automatically redirects
to ozone debug auditparser :
warning: 'ozone auditparser' is deprecated, use 'ozone debug auditparser'
instead.
• checknative (Deprecated): Similar to auditparser , this is a legacy
command that is accepted with a deprecation warning and automatically rerouted
to ozone debug checknative :
warning: 'ozone checknative' is deprecated, use 'ozone debug checknative'
instead.
──────
### 3. Typographical and Grammatical Errors
• --jvmargs Option Typo:
• Help Text: "...Any defined in OZONE_CLIENT_OPTS will be append after
these jvmargs"
• Fix: Change append to appended (e.g., "...will be appended after
these jvmargs" ).
• --validate (continue) Option Clutter:
• Help Text: "...as indicated in the corresponding
OZONE_RUN_ARTIFACT_NAME classpath file..."
• Fix: Reference to the internal developer variable
OZONE_RUN_ARTIFACT_NAME is leaky and confusing for normal users. It should be
simplified to
describe that it validates the classpath jars.
──────
### 4. ⚠️ Developer Code Bug (Discovered in AutoCompletion.java )
There is a major description discrepancy inside the Java class
AutoCompletion.java which is used to generate the bash/zsh shell
auto-completion
scripts.
In
/hadoop-ozone/tools/src/main/java/org/apache/hadoop/ozone/utils/AutoCompletion.java
(lines 141–143):
@Option(names = {"--daemon"},
description = "attempt to add class files from build tree")
private String daemon;
• The Bug: The description for the --daemon option was accidentally
copy-pasted from the --buildpaths option ( "attempt to add class files from
build tree" ).
• The Correct Behavior: It should be "operate on a daemon" (accepting
start|status|stop ). As a result, the auto-completion scripts generated via
ozone completion will provide incorrect helper text for --daemon .
──────
### 5. Confusing / Outdated Design
• --validate (continue) Syntax:
• The help message formats this as --validate (continue) . The
parenthesis notation is ambiguous. It's not clear to an end-user whether they
should type --validate continue or --validate (continue) literally.
• A clearer representation would be --validate [continue] .
• csi Daemon Command:
• The csi (Container Storage Interface) daemon command is still listed
under Daemon Commands. In recent Kubernetes and container orchestration
setups, Ozone integrates through modern standard CSI plugins, making this
standalone CSI daemon command mostly legacy or obsolete for most
production deployments.
{noformat}
> Update Ozone command help menu
> ------------------------------
>
> Key: HDDS-15420
> URL: https://issues.apache.org/jira/browse/HDDS-15420
> Project: Apache Ozone
> Issue Type: Bug
> Affects Versions: 2.1.1
> Reporter: Wei-Chiu Chuang
> Priority: Major
>
> The Ozone command help menu is outdated, and can use some help.
> {noformat}
> $ /opt/ozone/bin/ozone
> Usage: ozone [OPTIONS] SUBCOMMAND [SUBCOMMAND OPTIONS] OPTIONS is none or
> any of:--buildpaths attempt to add class files from
> build tree
> --config dir Ozone config directory
> --daemon (start|status|stop) operate on a daemon
> --debug turn on shell script debug mode
> --help usage information
> --hostnames list[,of,host,names] hosts to use in worker mode
> --hosts filename list of hosts to use in worker mode
> --jvmargs arguments append JVM options to any existing options
> defined in the OZONE_OPTS environment variable. Any defined in
> OZONE_CLIENT_OPTS will be append after
> these jvmargs
> --loglevel level set the log4j level for this command
> --validate (continue) validates if all jars as indicated in the
> corresponding OZONE_RUN_ARTIFACT_NAME classpath file are present, command
> execution shall continue post validation
> failure if 'continue' is passed
> --workers turn on worker mode SUBCOMMAND is one of:
> Admin Commands:daemonlog get/set the log level for each daemon
> Client Commands:admin Ozone admin tool
> classpath prints the class path needed for running ozone commands
> completion generate autocompletion script for bash/zsh
> debug Ozone debug tool
> dtutil operations related to delegation tokens
> envvars display computed Hadoop environment variables
> freon runs an ozone data generator
> fs run a filesystem command on Ozone file system. Equivalent to
> 'hadoop fs'
> genconf generate minimally required ozone configs and output to
> ozone-site.xml in specified path
> getconf get ozone config values from configuration
> insight tool to get runtime operation information
> ratis Ozone ratis tool
> repair Ozone repair tool
> s3 command line interface for s3 related operations
> sh command line interface for object store operations
> tenant command line interface for multi-tenant related operations
> version print the version Daemon Commands:csi run the
> standalone CSI daemon
> datanode run a HDDS datanode
> httpfs run the HTTPFS compatible REST gateway
> om Ozone Manager
> recon run the Recon service
> s3g run the S3 compatible REST gateway
> scm run the Storage Container Manager serviceSUBCOMMAND may print
> help when invoked w/o parameters or with -h. {noformat}
> Here's the suggested change:
> {noformat}
> Based on a deep-dive review of the Apache Ozone shell entrypoint script (
> ozone ), its helper library ( ozone-functions.sh ), and the Java auto-
> completion
> generation tools ( AutoCompletion.java ), here is the comprehensive
> analysis of incorrect, missing, confusing, and outdated items in the provided
> help
> message.
> ──────
> ### 1. Missing Subcommands
> There are two fully implemented and supported Client Commands in the ozone
> script that are completely missing from the help message:
> • interactive : An interactive shell for Ozone commands.
> • Registration in code: ozone_add_subcommand "interactive" client
> "interactive shell for ozone commands"
> • vapor : An Ozone server simulator (often used for benchmarks and
> high-throughput generator simulation).
> • Registration in code: ozone_add_subcommand "vapor" client "Ozone
> server simulator"
> ──────
> ### 2. Missing Aliases & Undocumented Deprecated Commands
> • shell (Alias): In the entrypoint script, the command shell is
> accepted as an alias/synonym for sh (refer to sh | shell) inside the
> subcommand
> case handler). It is fully supported but undocumented in the help list.
> • auditparser (Deprecated): This legacy command is deprecated and no
> longer documented. If executed, it outputs a warning and automatically
> redirects
> to ozone debug auditparser :
> warning: 'ozone auditparser' is deprecated, use 'ozone debug auditparser'
> instead.
> • checknative (Deprecated): Similar to auditparser , this is a legacy
> command that is accepted with a deprecation warning and automatically rerouted
> to ozone debug checknative :
> warning: 'ozone checknative' is deprecated, use 'ozone debug checknative'
> instead.
> ──────
> ### 3. Typographical and Grammatical Errors
> • --jvmargs Option Typo:
> • Help Text: "...Any defined in OZONE_CLIENT_OPTS will be append after
> these jvmargs"
> • Fix: Change append to appended (e.g., "...will be appended after
> these jvmargs" ).
> • --validate (continue) Option Clutter:
> • Help Text: "...as indicated in the corresponding
> OZONE_RUN_ARTIFACT_NAME classpath file..."
> • Fix: Reference to the internal developer variable
> OZONE_RUN_ARTIFACT_NAME is leaky and confusing for normal users. It should
> be simplified to
> describe that it validates the classpath jars.
> ──────
> ### 4. ⚠️ Developer Code Bug (Discovered in AutoCompletion.java )
> There is a major description discrepancy inside the Java class
> AutoCompletion.java which is used to generate the bash/zsh shell
> auto-completion
> scripts.
> In
> /hadoop-ozone/tools/src/main/java/org/apache/hadoop/ozone/utils/AutoCompletion.java
> (lines 141–143):
> @Option(names = {"--daemon"},
> description = "attempt to add class files from build tree")
> private String daemon;
> • The Bug: The description for the --daemon option was accidentally
> copy-pasted from the --buildpaths option ( "attempt to add class files from
> build tree" ).
> • The Correct Behavior: It should be "operate on a daemon" (accepting
> start|status|stop ). As a result, the auto-completion scripts generated via
> ozone completion will provide incorrect helper text for --daemon .
> ──────
> ### 5. Confusing / Outdated Design
> • --validate (continue) Syntax:
> • The help message formats this as --validate (continue) . The
> parenthesis notation is ambiguous. It's not clear to an end-user whether they
> should type --validate continue or --validate (continue) literally.
> • A clearer representation would be --validate [continue] .
> • csi Daemon Command:
> • The csi (Container Storage Interface) daemon command is still
> listed under Daemon Commands. In recent Kubernetes and container orchestration
> setups, Ozone integrates through modern standard CSI plugins, making
> this standalone CSI daemon command mostly legacy or obsolete for most
> production deployments.
> {noformat}
> Also the 'ozone envvars' command should refer to "Ozone" instead of "Hadoop"
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
