Bug 1525560
Summary: | vdo --help is not listed correctly | ||||||||
---|---|---|---|---|---|---|---|---|---|
Product: | Red Hat Enterprise Linux 7 | Reporter: | Jakub Krysl <jkrysl> | ||||||
Component: | vdo | Assignee: | Joe Shimkus <jshimkus> | ||||||
Status: | CLOSED ERRATA | QA Contact: | Jakub Krysl <jkrysl> | ||||||
Severity: | unspecified | Docs Contact: | |||||||
Priority: | unspecified | ||||||||
Version: | 7.5 | CC: | awalsh, bgurney, jkrysl, jochapma, jshimkus, limershe, lmiksik | ||||||
Target Milestone: | rc | ||||||||
Target Release: | --- | ||||||||
Hardware: | Unspecified | ||||||||
OS: | Unspecified | ||||||||
Whiteboard: | |||||||||
Fixed In Version: | 6.1.0.105 | Doc Type: | If docs needed, set a value | ||||||
Doc Text: | Story Points: | --- | |||||||
Clone Of: | Environment: | ||||||||
Last Closed: | 2018-04-10 15:49:25 UTC | Type: | Bug | ||||||
Regression: | --- | Mount Type: | --- | ||||||
Documentation: | --- | CRM: | |||||||
Verified Versions: | Category: | --- | |||||||
oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |||||||
Cloudforms Team: | --- | Target Upstream Version: | |||||||
Embargoed: | |||||||||
Attachments: |
|
Description
Jakub Krysl
2017-12-13 14:55:19 UTC
Created attachment 1367496 [details]
'vdo --help' in previous version
The display is the default behavior of the python argparse module following its 'command' structure paradigm where the high-level commands are only named when run as 'vdo --help'. Help for individual commands is available via 'vdo <command> --help'. This provides the same level of detail as previous vdo implementations but displays only those options and arguments applicable to the specified command; an improvement in not cluttering the help with non-applicable options. If there is a particular format desired for the high-level 'vdo --help' please let us know. We can certainly look into providing such. Hi Joe, I agree with just listing the commands with 'vdo --help' and providing help to individual commands on demand by 'vdo /command/ --help'. The issue here is with the listing itself, as it is quite hard to read. Much better approach is for example what lvm does. Plus it not only lists the commands but also ads short description to each of them: $ lvm --help Available lvm commands: Use 'lvm help <command>' for more information config Display and manipulate configuration information devtypes Display recognised built-in block device types dumpconfig Display and manipulate configuration information formats List available metadata formats help Display help for commands fullreport Display full report lastlog Display last command's log report lvchange Change the attributes of logical volume(s) lvconvert Change logical volume layout lvcreate Create a logical volume lvdisplay Display information about a logical volume lvextend Add space to a logical volume lvmchange With the device mapper, this is obsolete and does nothing. lvmconfig Display and manipulate configuration information lvmdiskscan List devices that may be used as physical volumes lvmsadc Collect activity data lvmsar Create activity report lvreduce Reduce the size of a logical volume lvremove Remove logical volume(s) from the system lvrename Rename a logical volume lvresize Resize a logical volume lvs Display information about logical volumes lvscan List all logical volumes in all volume groups pvchange Change attributes of physical volume(s) pvresize Resize physical volume(s) pvck Check the consistency of physical volume(s) pvcreate Initialize physical volume(s) for use by LVM pvdata Display the on-disk metadata for physical volume(s) pvdisplay Display various attributes of physical volume(s) pvmove Move extents from one physical volume to another lvpoll Continue already initiated poll operation on a logical volume pvremove Remove LVM label(s) from physical volume(s) pvs Display information about physical volumes pvscan List all physical volumes segtypes List available segment types systemid Display the system ID, if any, currently set on this host tags List tags defined on this host vgcfgbackup Backup volume group configuration(s) vgcfgrestore Restore volume group configuration vgchange Change volume group attributes vgck Check the consistency of volume group(s) vgconvert Change volume group metadata format vgcreate Create a volume group vgdisplay Display volume group information vgexport Unregister volume group(s) from the system vgextend Add physical volumes to a volume group vgimport Register exported volume group with system vgimportclone Import a VG from cloned PVs vgmerge Merge volume groups vgmknodes Create the special files for volume group devices in /dev vgreduce Remove physical volume(s) from a volume group vgremove Remove volume group(s) vgrename Rename a volume group vgs Display information about volume groups vgscan Search for all volume groups vgsplit Move physical volumes into a new or existing volume group version Display software and driver version information Another example is libstoragemgmts cli 'lsmcli', attaching it as it is quite long. lsmcli has some common optional arguments and common command formatting so it is listing that too. AFAIK vdo has some common options applicable to all vdo commands, so it might be a good idea to list that too at this point. Also the common formatting listed here makes it more clear that user should use style 'vdo /command/ /option(s)/' as this change was introduced very recently. Created attachment 1367864 [details]
lsmcli --help
The first part of vdo --help messega as it is now appears when using wrong option: # vdo create --name vdo --device /dev/sdd --wrongOption usage: vdo [-h] {activate,changeWritePolicy,create,deactivate,disableCompression,disableDeduplication,enableCompression,enableDeduplication,growLogical,growPhysical,list,modify,printConfigFile,remove,start,status,stop} ... vdo: error: unrecognized arguments: --wrongOption With a bit of massaging I've gotten argparse to produce the output detailed below.
Please comment on any issues with this output.
As to the display of the usage for the particular command which detects an incorrect
option (e.g., create --wrongOption), debugging argparse's behavior in the command subparser paradigm doesn't generate the error condition in the parser that detects the error (if it did, we'd be all set). Rather, it returns an indication to its parent that it found incorrect option(s) and the parent generates the error condition. Thus the command-specific state information is lost. I have some ideas on how to get it to do what we want, but nothing definite yet.
-----------------------
> ./vdo --help
usage: vdo [-h] command ...
Manage kernel VDO devices and related configuration information. For help on
individual commands specify the command followed by --help.
optional arguments:
-h, --help show this help message and exit
management commands:
command description
activate Activates one or more VDO volumes. Activated volumes
can be started using the 'start' command. This command
must be run with root privileges.
changeWritePolicy Modifies the write policy of one or all running VDO
volumes. This command must be run with root
privileges.
create Creates a VDO volume and its associated index and
makes it available unless --activate=disabled is
specified. Will not overwrite an existing file system
or formatted VDO volume unless --force is given. This
command must be run with root privileges.
deactivate Deactivates one or more VDO volumes. Deactivated
volumes cannot be started by the 'start' command.
Deactivating a currently running volume does not stop
it, but once stopped it must be activated before it
can be started again. This command must be run with
root privileges.
disableCompression Disables compression on one or more VDO volumes. If
the VDO volume is running, takes effect immediately;
otherwise compression will be disabled the next time
the VDO volume is started. This command must be run
with root privileges.
disableDeduplication
Disables deduplication on one more VDO volumes. If the
VDO volume is running, deduplication will be stopped
as well; otherwise, deduplication will be disabled the
next time the VDO volume is started. This command must
be run with root privileges.
enableCompression Enables compression on one or more VDO volumes. If the
VDO volume is running, takes effect immediately;
otherwise compression will be enabled the next time
the VDO volume is started. This command must be run
with root privileges.
enableDeduplication
Enables deduplication on one or more VDO volumes. If
the VDO volume is running, deduplication will be
started as well; otherwise, deduplication will be
enabled the next time the VDO volume is started. This
command must be run with root privileges.
growLogical Grows the logical size of a VDO volume. The volume
must exist and must be running. This command must be
run with root privileges.
growPhysical Grows the physical size of a VDO volume. The volume
must exist and must be running. This command must be
run with root privileges.
list Displays a list of started VDO volumes. If --all is
specified it displays both started and non-started
volumes.
modify Modifies configuration parameters of one or all VDO
volumes. Changes take effect the next time the VDO
device is started; already-running devices are not
affected.
printConfigFile Prints the configuration file to stdout.
remove Removes one or more stopped VDO volumes and associated
indexes. This command must be run with root
privileges.
start Starts one or more stopped, activated VDO volumes and
associated services. This command must be run with
root privileges.
status Reports VDO system and volume status in YAML format.
Status information will be incomplete if the command
is not run with root privileges.
stop Stops one or more running VDO volumes and associated
services. This command must be run with root
privileges.
High-level help is now as below (less voluble than previously described):
-----------------------
> ./vdo --help
usage: vdo [-h] command ...
Manage kernel VDO devices and related configuration information. For help on
individual commands specify the command followed by --help. Unless otherwise
noted all commands must be run with root privileges.
optional arguments:
-h, --help show this help message and exit
management commands:
command description
activate Activates one or more VDO volumes. Activated volumes
can be started using the 'start' command.
changeWritePolicy Modifies the write policy of one or all running VDO
volumes.
create Creates a VDO volume and its associated index and
makes it available.
deactivate Deactivates one or more VDO volumes. Deactivated
volumes cannot be started by the 'start' command.
Deactivating a currently running volume does not stop
it.
disableCompression Disables compression on one or more VDO volumes. If
the VDO volume is running, takes effect immediately.
disableDeduplication
Disables deduplication on one more VDO volumes. If the
VDO volume is running, takes effect immediately.
enableCompression Enables compression on one or more VDO volumes. If the
VDO volume is running, takes effect immediately.
enableDeduplication
Enables deduplication on one or more VDO volumes. If
the VDO volume is running, takes effect immediately.
growLogical Grows the logical size of a VDO volume. The volume
must exist and must be running.
growPhysical Grows the physical size of a VDO volume. The volume
must exist and must be running.
list Displays a list of started VDO volumes. If --all is
specified it displays both started and non-started
volumes.
modify Modifies configuration parameters of one or all VDO
volumes. Changes take effect the next time the VDO
device is started; already-running devices are not
affected.
printConfigFile Prints the configuration file to stdout. This command
does not require root privileges.
remove Removes one or more stopped VDO volumes and associated
indexes.
start Starts one or more stopped, activated VDO volumes and
associated services.
status Reports VDO system and volume status in YAML format.
This command does not require root privileges though
information will be incomplete if run without.
stop Stops one or more running VDO volumes and associated
services.
Error reporting of unrecognized arguments is now command-specific. As an example...
-----------------------
> ./vdo activate --all --unknown
usage: vdo activate [-h] (-a | -n <volume>) [-f <file>] [--logfile <pathname>]
[--verbose]
vdo activate: error: unrecognized arguments: --unknown
Great job! # vdo --help usage: vdo [-h] command ... Manage kernel VDO devices and related configuration information. For help on individual commands specify the command followed by --help. Unless otherwise noted all commands must be run with root privileges. optional arguments: -h, --help show this help message and exit management commands: command description activate Activates one or more VDO volumes. Activated volumes can be started using the 'start' command. changeWritePolicy Modifies the write policy of one or all running VDO volumes. create Creates a VDO volume and its associated index and makes it available. deactivate Deactivates one or more VDO volumes. Deactivated volumes cannot be started by the 'start' command. Deactivating a currently running volume does not stop it. disableCompression Disables compression on one or more VDO volumes. If the VDO volume is running, takes effect immediately. disableDeduplication Disables deduplication on one more VDO volumes. If the VDO volume is running, takes effect immediately. enableCompression Enables compression on one or more VDO volumes. If the VDO volume is running, takes effect immediately. enableDeduplication Enables deduplication on one or more VDO volumes. If the VDO volume is running, takes effect immediately. growLogical Grows the logical size of a VDO volume. The volume must exist and must be running. growPhysical Grows the physical size of a VDO volume. The volume must exist and must be running. list Displays a list of started VDO volumes. If --all is specified it displays both started and non-started volumes. modify Modifies configuration parameters of one or all VDO volumes. Changes take effect the next time the VDO device is started; already-running devices are not affected. printConfigFile Prints the configuration file to stdout. This command does not require root privileges. remove Removes one or more stopped VDO volumes and associated indexes. start Starts one or more stopped, activated VDO volumes and associated services. status Reports VDO system and volume status in YAML format. This command does not require root privileges though information will be incomplete if run without. stop Stops one or more running VDO volumes and associated services. # vdo unknown --help usage: vdo [-h] command ... vdo: error: argument command: invalid choice: 'unknown' (choose from 'activate', 'changeWritePolicy', 'create', 'deactivate', 'disableCompression', 'disableDeduplication', 'enableCompression', 'enableDeduplication', 'growLogical', 'growPhysical', 'list', 'modify', 'printConfigFile', 'remove', 'start', 'status', 'stop') # vdo create --name vdo --device /dev/sde --unknown usage: vdo create [-h] -n <volume> --device <devicepath> [--activate {disabled,enabled}] [--blockMapCacheSize <megabytes>] [--blockMapPeriod <period>] [--compression {disabled,enabled}] [--deduplication {disabled,enabled}] [--emulate512 {disabled,enabled}] [--force] [--indexMem <gigabytes>] [--readCache {disabled,enabled}] [--readCacheSize <megabytes>] [--sparseIndex {disabled,enabled}] [--vdoAckThreads <threadCount>] [--vdoBioRotationInterval <ioCount>] [--vdoBioThreads <threadCount>] [--vdoCpuThreads <threadCount>] [--vdoHashZoneThreads <threadCount>] [--vdoLogicalSize <megabytes>] [--vdoLogicalThreads <threadCount>] [--vdoLogLevel {critical,error,warning,notice,info,debug}] [--vdoPhysicalThreads <threadCount>] [--vdoSlabSize <megabytes>] [--writePolicy {async,sync}] [-f <file>] [--logfile <pathname>] [--verbose] vdo create: error: unrecognized arguments: --unknown Since the problem described in this bug report should be resolved in a recent advisory, it has been closed with a resolution of ERRATA. For information on the advisory, and where to find the updated files, follow the link below. If the solution does not work for you, open a new bug report. https://access.redhat.com/errata/RHEA-2018:0871 |