Bug 1508920
| Summary: | vdo manager 'create/remove' command documentation | ||
|---|---|---|---|
| Product: | Red Hat Enterprise Linux 7 | Reporter: | Joe Shimkus <jshimkus> |
| Component: | doc-Storage_Administration_Guide | Assignee: | Marek Suchánek <msuchane> |
| Status: | CLOSED CURRENTRELEASE | QA Contact: | Zhang Kexin <kzhang> |
| Severity: | unspecified | Docs Contact: | |
| Priority: | unspecified | ||
| Version: | 7.5 | CC: | rhel-docs |
| Target Milestone: | rc | Keywords: | Documentation |
| Target Release: | --- | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | If docs needed, set a value | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2018-03-13 18:51:18 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: | |||
| Bug Depends On: | |||
| Bug Blocks: | 1495322, 1552784 | ||
Hello Joe, Thanks for reporting this. Currently, we're preparing just a brief Quick Start chapter for VDO, which will be released for Alpha to help early adopters test VDO basics. We will publish more complete, regular documentation later, that is, for Beta or GA. Is it OK for me to leave this bug for the later docs release? (In reply to Marek Suchanek from comment #2) > Hello Joe, > > Thanks for reporting this. Currently, we're preparing just a brief Quick > Start chapter for VDO, which will be released for Alpha to help early > adopters test VDO basics. We will publish more complete, regular > documentation later, that is, for Beta or GA. > > Is it OK for me to leave this bug for the later docs release? Marek, I think delaying until Beta would be fine. This is what should be an exceptional and extremely rare occurrence (outside of qualification testing). OK, I'm attaching this to our main VDO docs bug as a blocker. I've rewritten your draft and added the content to the 29.4.4. "Removing VDO Volumes" section: https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/integrating-vdo#vdo-ig-remove-volume Also, I've added a link to the section from 29.4.3. "Creating VDO Volumes". Can you please check if the section is correct? My comments prefixed with JBS>.
29.4.4.1. Removing an Unsuccessfully Created Volume
If the administrator has changed the system configuration since the volume was unsuccessfully created, a conflict might occur. The vdo remove command then fails with the following message:
JBS> Strictly speaking, if the create was interrupted vdo remove (w/o --force) will always fail w/ the
JBS> generated output. It doesn't attempt to check if anything has changed, it presumes arbitrary time has
JBS> passed and that the configuration may have changed.
29.4.8. Automatically Enabling or Disabling VDO Volumes at Startup
29.4.9. Disabling and Re-enabling Deduplication
JBS> As with compression, activation and deduplication can be specified at create.
JBS> activate = { enabled | disabled }
JBS> deduplication = { enabled | disabled }
JBS> That doesn't *have* to be mentioned in these sections, but it is mentioned for compression.
29.7.1. vdo
JBS> The synopsis is incorrect. The format of a command is:
JBS> vdo <subcommand> [ OPTIONS ]
JBS> where the [ OPTIONS ] are constrained by the < subcommand > specified.
JBS> This is enforced by the argument parser construct being used.
Table 29.1. VDO Sub-Commands
JBS> The 'list' subcommand also takes the option '--all'.
JBS> Without it only the started vdos are listed; with it non-started vdos (from the config file) are
JBS> also listed.
JBS> The 'modify' subcommand does not take the option '--writePolicy'.
JBS> It will be re-instated in a subsequent release, but is no longer there currently.
Table 29.2. VDO Options
JBS> --blockMapPeriod; description references Permabit.
JBS> --confFile; the default is a '.yml' file, not '.xml'.
JBS> --readCache; default 'disabled' is not bolded
JBS> --vdoSlabSize; S of S(actors) is not bolded
Table 29.3. VDO Status Output
JBS> Key 'Write policy' actually 'Configured write policy'. Also, the description does not include
JBS> auto as an option. However, this is consistent with the man page (for which B Z1542700 has been
JBS> submitted).
Table 29.6. vdostats --verbose Output
JBS> 'Write policy' description references 'vdo modify'; see issue above re: modify.
JBS> Also, this write policy field represents either the specific policy (async/sync) specified by the
JBS> administrator or the policy selected by vdo (again, async/sync) if the administrator specified
JBS> 'auto'.
JBS> That's all! :-)
Thanks for the comments. (In reply to Joe Shimkus from comment #6) > My comments prefixed with JBS>. > > 29.4.4.1. Removing an Unsuccessfully Created Volume > If the administrator has changed the system configuration since the volume > was unsuccessfully created, a conflict might occur. The vdo remove command > then fails with the following message: > JBS> Strictly speaking, if the create was interrupted vdo remove (w/o > --force) will always fail w/ the > JBS> generated output. It doesn't attempt to check if anything has changed, > it presumes arbitrary time has > JBS> passed and that the configuration may have changed. I've changed the procedure to always require the "--force" option: https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-integrating-vdo#vdo-ig-removing-unsuccessfully-created-volume > 29.4.8. Automatically Enabling or Disabling VDO Volumes at Startup > 29.4.9. Disabling and Re-enabling Deduplication > JBS> As with compression, activation and deduplication can be specified at > create. > JBS> activate = { enabled | disabled } > JBS> deduplication = { enabled | disabled } > JBS> That doesn't *have* to be mentioned in these sections, but it is > mentioned for compression. Added the options to the activation and deduplication section: * https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-integrating-vdo#vdo-ig-enable-disable-volume * https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-integrating-vdo#vdo-ig-stop-start-dedupe > 29.7.1. vdo > JBS> The synopsis is incorrect. The format of a command is: > JBS> vdo <subcommand> [ OPTIONS ] > JBS> where the [ OPTIONS ] are constrained by the < subcommand > specified. > JBS> This is enforced by the argument parser construct being used. I've copy-and-pasted synopsis from the man page: https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#cmd-vdo > Table 29.1. VDO Sub-Commands > JBS> The 'list' subcommand also takes the option '--all'. > JBS> Without it only the started vdos are listed; with it non-started vdos > (from the config file) are > JBS> also listed. Added "--all": https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_cmd_list > JBS> The 'modify' subcommand does not take the option '--writePolicy'. > JBS> It will be re-instated in a subsequent release, but is no longer there > currently. Removed "--writePolicy": https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_cmd_modify > Table 29.2. VDO Options > JBS> --blockMapPeriod; description references Permabit. Changed to "Red Hat": https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_blockMapPeriod > JBS> --confFile; the default is a '.yml' file, not '.xml'. Changed to "/etc/vdoconf.yml": https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_confFile > JBS> --readCache; default 'disabled' is not bolded > JBS> --vdoSlabSize; S of S(actors) is not bolded Bolded both: * https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_readCache * https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#vdo_opt_vdoSlabSize > Table 29.3. VDO Status Output > JBS> Key 'Write policy' actually 'Configured write policy'. Changed to "Configured write policy": https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#tbl_vdostats_output_verbose > Also, the > description does not include > JBS> auto as an option. However, this is consistent with the man page (for > which B Z1542700 has been > JBS> submitted). > > Table 29.6. vdostats --verbose Output > JBS> 'Write policy' description references 'vdo modify'; see issue above re: > modify. Changed the command to "vdo changeWritePolicy --writePolicy=auto|sync|async": https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#tbl_vdostats_output_verbose > JBS> Also, this write policy field represents either the specific policy > (async/sync) specified by the > JBS> administrator or the policy selected by vdo (again, async/sync) if the > administrator specified > JBS> 'auto'. I've added "The *active* write policy (sync or async)" to be a bit clearer. You're gonna want to kill me... I mistakenly treated the 'vdostats --verbose' output as if it was the output of 'vdo status'. "Write policy" is the correct name for this item. https://access.qa.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-ig-commands#tbl_vdostats_output_verbose Everything else looks fine. No problem, I've fixed it already :-) Moving this bug to VERIFIED. Content from the VDO Integration Guide has been published on the Customer Portal: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/storage_administration_guide/vdo-integration Therefore, I'm closing this bug as CURRENTRELEASE. |
The following needs to be incorporated in to the vdo manager documentation concerning the create/remove operations. In the event of a failure that prevents vdo manager from successfully completing a 'create' operation (system crash, power failure, administrator interrupting the command, etc.) the process of creating the vdo device is left in an intermediate state. The appropriate manner of cleaning up from this situation is to execute a 'vdo remove' operation specifying the vdo device that was being created. However, as there is no requirement to perform such cleanup for the system as a whole to function it is possible that an arbitrary amount of time has elapsed since the creation failure. Because of the possibility that during this elapsed period the administrator has configured the system in a way that conflicts with its state at the time of attempted vdo device creation simply running 'vdo remove' against the vdo device will produce output similar to the following: # vdo remove --name=vdo Removing VDO vdo Stopping VDO do A previous operation failed. Recovery from the failure either failed or was interrupted. Add '--force' to 'remove' to perform the following cleanup. Steps to clean up VDO vdo: umount -f /dev/mapper/vdo udevadm settle dmsetup remove vdo vdo: ERROR - VDO volume vdo previous operation (create) is incomplete providing the administrator with the steps that will be taken, if confirmed. To confirm the performance of the removal steps the administrator must run the 'vdo remove' command with the '--force' option.