Skip to content

HDDS-15420. Update Ozone command help menu#10404

Open
chihsuan wants to merge 7 commits into
apache:masterfrom
chihsuan:HDDS-15420
Open

HDDS-15420. Update Ozone command help menu#10404
chihsuan wants to merge 7 commits into
apache:masterfrom
chihsuan:HDDS-15420

Conversation

@chihsuan
Copy link
Copy Markdown
Contributor

@chihsuan chihsuan commented Jun 1, 2026

What changes were proposed in this pull request?

The ozone command help menu (ozone --help) and the generated shell autocompletion contained outdated, incorrect, and confusing entries. This PR cleans them up:

  • --jvmargs: fix typo "will be append" → "will be appended".
  • --validate: change the ambiguous (continue) notation to [continue] (square brackets denote the optional argument), and reword the description to drop the leaky internal OZONE_RUN_ARTIFACT_NAME variable in favor of user-facing wording. Applied to all three copies: the shell usage menu, the autocompletion generator, and the --validate misuse/error message in ozone-functions.sh.
  • envvars: refer to "Ozone" instead of "Hadoop" environment variables, in both the shell usage menu and the tools docs page.
  • --daemon (autocompletion source): fix a description accidentally copy-pasted from --buildpaths; it now reads "operate on a daemon".
  • shell alias: the shell alias for sh is accepted by the ozone script but was undocumented and unknown to the autocompletion generator. Note it in the usage menu and register it on the OzoneShell command so generated bash/zsh completion lists and dispatches shell as well.

Each change is a separate commit. A few items mentioned in the Jira are intentionally scoped out of this PR, and I'm happy to revisit if reviewers prefer otherwise:

  • csi: the Jira suggests it may be legacy. But it seems currently an alpha-but-documented, shipped interface with no in-repo replacement, and deprecating a daemon feels like a separate decision (own Jira + dev-list) rather than a help-text cleanup. Left as-is here.
  • auditparser / checknative: already deprecated and redirected with a warning; since deprecated commands are normally not advertised in the menu, I left them out, but can document them if preferred.

What is the link to the Apache JIRA

https://issues.apache.org/jira/browse/HDDS-15420

How was this patch tested?

Built a distribution (mvn clean install -DskipTests -Pdist) and verified against the running binary:

  • ozone --help shows all four updated usage lines (--jvmargs appended, --validate [continue], envvars → Ozone, sh ... (alias: shell)).
Details
> ozone --help

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 appended after these jvmargs
--loglevel level                   set the log4j level for this command
--validate [continue]              validate that all required jars are present on the classpath; with 'continue', keep running even if validation fails
--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 Ozone 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
interactive   interactive shell for ozone commands
ratis         Ozone ratis tool
repair        Ozone repair tool
s3            command line interface for s3 related operations
sh            command line interface for object store operations (alias: shell)
tenant        command line interface for multi-tenant related operations
vapor         Ozone server simulator
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 service

SUBCOMMAND may print help when invoked w/o parameters or with -h.
  • ozone shell --help routes to OzoneShell (the alias is functional).
Details
> ./bin/ozone shell --help

Usage: ozone sh [-hV] [--verbose] [-conf=<configurationPath>]
                [-D=<String=String>]... [--interactive | --execute=<command>
                [--execute=<command>]...] [COMMAND]
Shell for Ozone object store
      -conf=<configurationPath>

  -D, --set=<String=String>
      --execute=<command>   Run command as part of batch
  -h, --help                Show this help message and exit.
      --interactive         Run in interactive mode
  -V, --version             Print version information and exit.
      --verbose             More verbose output. Show the stack trace of the
                              errors.
Commands:
  bucket       Bucket specific operations
  key          Key specific operations
  prefix       Prefix specific operations
  snapshot     Snapshot specific operations
  user         Tenant user management
  token        Token specific operations
  volume, vol  Volume specific operations
  • ozone completion bash lists both sh and shell in the top-level candidate list and dispatcher.
  • checkstyle:check passes on the changed modules (hadoop-ozone/tools, hadoop-ozone/cli-shell).

chihsuan added 7 commits June 1, 2026 22:58
Change 'will be append' to 'will be appended' in the --jvmargs option description.
Use [continue] to denote the optional argument and drop the internal OZONE_RUN_ARTIFACT_NAME reference from the user-facing description, in both the shell usage menu and the autocompletion generator.
…urce

The --daemon option description was accidentally copied from --buildpaths. Correct it to 'operate on a daemon' for source consistency. (picocli's generated completion emits option names only, so this is not user-visible today.)
The 'shell' alias for 'sh' is accepted by the ozone script but was undocumented and unknown to the autocompletion generator. Note it in the usage menu and register it on the OzoneShell command, so generated bash/zsh completion lists and dispatches 'shell' as well.
…ge text

The --validate misuse/error message and its function doc still named the internal OZONE_RUN_ARTIFACT_NAME variable. Reword to user-facing text, consistent with the usage menu and autocompletion descriptions.
@chihsuan chihsuan marked this pull request as ready for review June 1, 2026 15:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant