vgversion(1M) vgversion(1M)
NAME
vgversion - handles volume group version migration of an existing LVM volume group
SYNOPSIS
vg_version_new vg_name
Remarks
The original version of LVM volume group is version 1.0 which is supported on all HP-UX 11i releases. LVM volume group version 2.0 was
introduced on the March 2008 update of HP-UX 11i v3 and is available for all updates on HP 11i v3 going forward. Versions 2.0 or higher
volume groups allow LVM to increase many of the limits constraining the size of volume groups, logical volumes, and so on. When con-
strained with the limits of the current configuration on version 1.0 volume group, the command can be used to extend a few of the version
1.0 volume group configuration limits.
For the HP-UX 11i v3 March 2009 Update and forward, a new command, is provided to take advantage of the improvements in volume group ver-
sion 2.0 or higher. The command allows in-place volume group migration from 1.0 to 2.0 or higher. The command also supports migration of a
volume group from any version 2.x to any other version 2.y.
DESCRIPTION
The command allows users to review and migrate the volume group version vg_version_old of an existing volume group vg_name to the new vol-
ume group version vg_version_new.
Options and Arguments
Review mode.
Review the effect of migrating the existing volume group to volume group version vg_version_new but do not do the actual migra-
tion.
When run in this mode, no updates to or happens, nor the volume group configuration files of the existing volume group present
under are modified. This option can be used on an active volume group.
Verbose mode. Be verbose in reporting.
Specify the volume group version to which the existing volume
group has to be migrated. The vg_version_new should be in the format 2.x (where x starts from 0 and beyond).
vg_name The path name of a volume group to be migrated.
Supported Volume Group Migration
The command allows the migration between any two supported volume group versions with the exception of moving back to version 1.0.
The following steps list the typical usage scenario of the command while migrating a volume group vg_name to the volume group version
vg_version_new:
1) Use the option with the command, to review if vg_name can be migrated to volume group version vg_version_new.
If required by the above step, prepare vg_name for actual migration by :
o Modifying the LVM configuration characteristics of vg_name, if it is found to be not supported by the volume group version vg_ver-
sion_new.
o Creating required space to accommodate vg_version_new's metadata using either or increasing the LUN size.
2) Do the actual migration of the volume group vg_name:
o Appropriate recovery check points are created on the system by the command, as part of the migration, to support recovery following
any interruption during the volume group migration process or post successful migration.
o Following successful migration, vg_name is updated to the volume group version vg_version_new.
3) Ensure that the volume group vg_name is migrated successfully to the volume group version vg_version_new using vgdisplay(1M),
lvmadm(1M), and other LVM commands.
4) In either of the below cases, if required, run the restore script with the volume group vg_name configuration file available on the
system to restore the volume group vg_name to the original volume group version:
o The command was interrupted while migration was in progress
o Post successful migration to vg_version_new using the command.
The command succeeds when the below criteria are met:
o All physical volumes belonging to volume group vg_name have that additional free space required to accommodate the volume group version
vg_version_new metadata.
o All the current LVM configuration and characteristics of the existing volume group vg_name and its logical volumes and physical volumes
are supported by the volume group version vg_version_new.
The command is supported only on deactivated volume groups, but user can review the migration when the vg_name is active. All physical
volumes that belong to volume group vg_name must be available while performing the migration.
The volume group must be cluster unaware (use if vg_name were cluster aware) before migration is made. The command fails if the volume
group vg_name has a cluster lock disk (see cmquerycl(1M)). The cluster lock must be removed before initiating the volume group migration.
Before updating each of the physical volumes with the new metadata, creates the following files under the directory in preparation of
migration to volume group version vg_version_new:
o A restore script, which can be used to restore the volume group vg_name with the configuration of the volume group contained in the con-
figuration backup file specified to this restore script.
o A configuration backup file of the volume group vg_name which has the configuration of original volume group version. User must use
this file while restoring the volume group to original volume group version using the restore script.
o A configuration backup file, of the volume group vg_name which has the configuration of volume group version vg_version_new. User must
use this file while restoring the volume group to volume group version vg_version_new using the restore script.
o A disks_file, which contains the list of physical volumes in the volume group. The order of the physical volumes in this file is
decided by their order in or This file is generated to be used by the restore script.
o A mapfile, which has the names of the logical volumes in the volume group version 2.0 or higher. This file is generated to be used by
the restore script.
o A mapfile, which has the names of the logical volumes in the volume group version 1.0 (applicable for migration of volume group version
1.0 to 2.0 or higher). This file is generated to be used by the restore script.
Note: All the above files created during the command, continues to exist on the system at the directory. These files may be useful during
restoration to new volume group version or in the case of recovery to original volume group version. Use extreme caution before deleting
these files on the system or while using these files for restoration purposes with the vgcfgrestore(1M) command.
User data present on any of the physical volumes belonging to the volume group vg_name will be unaffected by the migration operation.
In volume groups version 1.0, LVM metadata is required to fit into a single physical extent. In volume groups version 2.0 and higher,
metadata is not restricted to an extent. The LVM metadata for volume groups version 2.0 and higher may consume more space than on volume
groups version 1.0. Please see the section in lvm(7) for more details.
Note: The major number changes from 64 to 128 when the volume group is upgraded from 1.0 to 2.0 or higher volume group version.
If the command is interrupted before it completes, recovery steps might be required. See the section below for details.
Using the Review Mode Option (-r) Prior to Migration
Users can use the review mode option of the command to check whether the migration operation is possible. For example, the option can be
used to check whether all physical volumes have the additional space required to accommodate the volume group version vg_version_new meta-
data. Review mode can be used when the volume group is in activated state. The review option of the provides the following details:
o Lists any feature or functionality contained in the existing volume group vg_name which will not be supported in the migrating volume
group version vg_version_new resulting in the failure of migration.
For each such failure, the command displays the corresponding corrective action to be taken to prepare the volume group for successful
migration.
o Whether all the physical volumes in the existing volume group vg_name have sufficient space to hold the metadata for the migrating vol-
ume group version vg_version_new.
For those physical volumes which do not have enough free space to store the metadata of volume group version vg_version_new, review mode
displays the corrective actions to be taken to prepare the volume group for successful migration (like freeing up required number of
extents at the end of the physical volume or increasing the size of the physical volume by a specified size).
Migration of Volume Group Version 1.0 to Volume Group Version 2.x
Below are points to consider when migrating from volume group version 1.0 to version 2.x.
o If there are any entries in the bad block directory of any physical volume in the volume group vg_name, fails the migration and reports
the physical volume holding entries in the bad block directory.
o The migration fails if the volume group vg_name has any physical volumes which are configured as standby or active spare.
o Volume group versions 2.0 and higher do not support root, boot, swap, or dump. If the volume group version of vg_name is 1.0 and is
configured with any of the above, the command fails the migration of such volume groups to version 2.0 or higher.
o The migration of the volume group version includes moving the configuration details of the volume group present in the file to the file,
and converting all the device special files present under the directory to the format of new volume group version vg_version_new. This
include changing the device file major and minor number.
o Except where noted above, the volume group version migration process retains all other LVM configuration/characteristics of the existing
volume group vg_name and its logical volumes and physical volumes. Following a successful volume group version migration, retains the
order of the physical volumes in the LVM configuration files.
Note: Volume group version 2.0 and higher do not support bad block relocation. If any logical volume belonging to the volume group vg_name
has bad block relocation enabled, the command will change the bad block relocation policy of the logical volume to 'NONE'.
Migration of Volume Group Version 2.x to Volume Group Version 2.y
Below is information regarding migration from volume group version 2.x to a later version 2.y.
o The volume group version migration process retains all the LVM configuration and characteristics of the volume group vg_name and its
logical and physical volumes.
Following the successful volume group version migration, retains the order of the physical volumes in the LVM configuration.
o The command will fail if the logical volume number of any logical volume, minor number of volume group vg_name and pv key of any physi-
cal volume in the volume group vg_name is beyond the supported limits even if the actual total number of logical volumes, physical vol-
umes and volume groups are still within the supported limits for volume group version vg_version_new.
o Volume group migration from 2.x to 2.y (for example, 2.0 to 2.1 or 2.1 to 2.0) can be done provided the configuration limits defined for
the volume group vg_name is supported by volume group version vg_version_new. For example, if the existing volume group has more logi-
cal volumes than it is supported by the volume group version vg_version_new, the migration will fail. Refer to the command output to
see the details of the maximum supported limits for all the supported volume group versions on LVM.
Creating Metadata Space When It Is Not Available on the Physical Volumes
If any physical volume(s) lacks the additional space required to hold the volume group version vg_version_new metadata, the review mode
option of lists the minimum size required on each such physical volume(s) for a successful migration.
To accommodate the space requirement for storing the metadata of the vg_version_new, the user can do one of the following, prior to re-run-
ning
o Free up the required space at the end of the physical volume, as suggested by the command review mode output, by relocating few user
data extents with the help of the command.
o Increase of the size of the LUN from storage device (the newly added space is not under LVMs control though) so as to minimally
accommodate volume group version vg_version_new metadata.
o Following successful command execution, if the newly added space is not completely used by the command, the user may use the command
to add extents to the physical volume that has been expanded using the LUN expansion earlier. Alternatively, the user may choose to
reduce this extra space on the physical volume by performing LUN contraction from the storage device.
Note: A combination of the above two options can also be used to create space for metadata. Wherever possible, it is preferable to add
extra space (LUN expansion from the storage device) rather than freeing up user extents.
There may be a combination of the two scenarios mentioned above. There may be some free space (not under LVMs control) available at the
end of the physical volume, but insufficient to place the entire metadata. In such cases, the command will use the free extents from the
bottom of the physical volume to place the remaining metadata.
Recovery
If is interrupted during its operation it may be necessary to re-apply the configuration to all the physical volumes belonging to the vol-
ume group vg_name. To assist with this process, the generates a restore script under the directory. The user can run this restore script
to bring back the volume group vg_name to its initial state. Alternatively, the user can run this restore script to restore the configura-
tion of volume group version vg_version_new, if the command successfully creates the corresponding configuration file.
To enable restoration of the volume group, saves the following files in directory on the system. Refer to the section for more information
on these files.
To re-apply the configuration to all the physical volumes belonging to the
volume group vg_name, enter the following command:
To apply the configuration of volume group vg_name with volume group version vg_version_new to all the physical volumes belonging to it,
enter the following command:
EXTERNAL INFLUENCES
Environment Variables
determines the language in which messages are displayed.
If is not specified or is null, it defaults to "C" (see lang(5)).
If any internationalization variable contains an invalid setting, all internationalization variables default to "C" (see environ(5)).
RETURN VALUE
returns one of the following values:
0 Successful completion.
>0 Error condition occurred.
EXAMPLES
Review the version change operation of a volume group named to volume group version 2.0:
Change the version of a volume group named to volume group version 2.0:
Change the version of a volume group named to volume group version 2.1:
Change the version of a volume group named /dev/vg01 to volume group version 2.1 and be verbose:
WARNINGS
o If the command is interrupted prior to completing its operation, then restoration to all physical volumes in the volume group may be
required. Use the restore script to accomplish this (see the section for more information).
o The migration of volume group version 1.0 to 2.0 or higher requires the kernel driver, which supports volume group version 2.0 or
higher, to be loaded.
o During migration of volume group version 1.0 to 2.0 or higher, all device special files associated with the vg_name may get recreated.
The applications need to take care of recreating the symlinks or hardlinks to the new device special files of the volume group vg_name
post successful migration.
FILES
Holds the existing volume group configuration having volume group version
vg_version_old.
This file contains the existing volume group configuration of volume group version
vg_version_new.
Holds the mapfile information for the original volume group.
This file contains the names of logical volumes of the volume group.
Holds the mapfile information for the volume group version
vg_version_new. This file contains the names of logical volumes of the volume group.
Holds the list of physical volumes in the volume group.
The order of physical volumes is decided by the order in which they are added in the or
A script created by
before making any update, to be used if the command is interrupted while committing the configuration changes to the physical vol-
umes. See the section for its usage.
SEE ALSO
boot(1M), lvlnboot(1M), mkboot(1M), pvcreate(1M), pvmove(1M), vgcfgbackup(1M), vgcfgrestore(1M), vgchange(1M), vgcreate(1M), vgdisplay(1M),
vgextend(1M), vgmodify(1M), vgreduce(1M), lvm(7).
vgversion(1M)