CVUPDATEFS

Section: Maintenance Commands (8)
Updated: January 2018


NAME

cvupdatefs – Commit a StorNext File System configuration change

SYNOPSIS

cvupdatefs [-bdfFGhlnv] [-c pathname] [-R NewFsName] [FsName] [FsPath]

DESCRIPTION

The cvupdatefs program is used to commit a configuration change to a StorNext file system. Possible configuration changes include stripe group list modification as well as file system journal modification.

The file system update program must be run on the machine that the File System Manager (FSM) is running on. This utility reads the configuration file and compares the configuration file against the current on-disk metadata configuration. If there are differences between the configuration and the on-disk metadata, the utility will display what changes need to be made to bring the file system metadata up to date.

NOTE: All metadata modification must be made on a stopped file system. It is recommended that the file system is stopped and cvfsck(8) has been run before making any changes to a file system configuration. Maintaining a backup of the original file system configuration file is also strongly recommended.

When a successful update is completed, the new configuration file is stored in the on-disk metadata and the previous one is saved in /usr/cvfs/data/<file_system_name>/config_history/*.cfgx.<TIMESTAMP>

OPTIONS

-b
Build info – log the build information.
-c pathname
Provide a specific path to the previous configuration file that is to be used. This option is used to force cvfsck to be run as a sub-process to insure that the file system meta data is consistent prior to doing a capacity or stripegroup expansion, or any journal changes.
-d
Debug – use to turn on internal debugging only.
-F
Force. This option has been deprecated and replaced with -y. It will cause the same action as that option.
-f
Failure mode – do not fail if there is a configuration mismatch or other serious abnormal condition detected. Note: This option is not intended for general use. Use only if instructed by Quantum support. Incorrect use may result in an unusable file system.
-G
Pause – pause the program after displaying the exit status (Windows only.)
-h
Help – print the synopsis for this command.
-l
Log – log when the update finished.
-n
Read-only – set metadata to read-only mode.
-R NewFsName
Rename – Provide a new file system name to rename an existing unmanaged file system. The existing config file will be renamed, and the existing data directory containing logs will be migrated to the new name. See the section below for further details about using this option.
-s
Slice rebuild – Rebuild the free slice trees to their optimal sizes. When extending the LUNs in a stripegroup, by default it will just add enough additional slices to hold the additional free space. When the -s option is given, it will instead rebuild the slice trees, which usually results in larger slices. If the LUNs have been previously extended, this option will allow the slice trees to be rebuilt without extending the LUNs.
-U
When a stripegroup is added, do a check for disks that are included in the stripegroup that is being added to see if they are currently in use in another file system that is visible to the cluster. In some configurations, this may take a long time. If there are disks in use, the operation is aborted.
-v
Verbose – turn on verbose reporting methods.
-y
Yes – Bypass the prompt and answer yes to the basic warning about proceeding. If the prompt warning is for an unusual condition, this option will not bypass that prompt.

Once the file system configuration has been changed to reflect the stripe group or journal changes the cvupdatefs utility may be run. When cvupdatefs is run it will display a listing of stripe groups which will be modified, followed by a prompt. If this list accurately reflects the changes made to the configuration file then answering ‘yes’ at the prompt will allow the utility to make the needed changes.

Once the utility has completed, the file system may be started again. After starting the file system, the ‘show’ command in cvadmin(8) may be used to verify the new stripe groups. The ‘show’ command will list all of the stripe groups on the file system, including the newly created stripe group(s). Also, if the location of the file system journal has changed this too will be reflected by the cvadmin command ‘show’.

WARNINGS

It is very important that the consistency of the file system be correct before cvupdatefs is run. If the file system has a bad state cvupdatefs could introduce data corruption. It is recommended that cvfsck is executed on the file system before any changes are made. If cvfsck does not finish with a clean file system do not make any configuration changes until the file system is clean.

ADDING A STRIPE GROUP

The first step in adding stripe groups is to modify the file system’s configuration file to reflect the desired changes. For notes on file system configuration format refer to snfs_config(5). In addition to adding StripeGroup configuration entries, associated Disk and DiskType entries for any new disks must be included.

Currently the ordering of stripe groups in the configuration file and in the metadata must match. Thus, when adding new stripe group configuration entries to the configuration file they must always be added to the end of the StripeGroup configuration section. cvupdatefs will abort if a new stripe group is detected anywhere but the end of the file.

INCREASING THE STRIPE DEPTH OF AN EXISTING STRIPE GROUP

Warning: This option is not recommended and its use is deprecated. Adding a new stripe group is the recommended way to expand capacity of a file system.

The stripe depth is the number of disks in the stripe group and is a key factor in the amount of parallel I/O that can be accomplished. This choice should ideally be made before the file system is created, thus eliminating the need for cvupdatefs to modify this value by adding disks to the stripe group. Consult the StorNext File System Tuning Guide for information on configuring for optimal file system performance.

Warning: When a stripe group is populated with file data, adding disks will increase free space fragmentation of the stripe group proportional to the amount of pre-existing file data. It is important to avoid fragmentation, which severely impacts performance and functionality of the file system. If the stripe group contains little or no file data, expansion will not result in free space fragmentation. The snfsdefrag utility can be used to relocate pre-existing file data to a different stripe group.

When new disks are added to an existing stripe group the new disks must exactly match the existing disks in size. All new disks must be added to the end in the disk list in the configuration file StripeGroup section.

New disks cannot be added to a stripe group containing metadata or journal. A new stripe group must be added if additional capacity or performance is needed for metadata or journal operations. The cvupdatefs utility can be used to relocate the journal to a new stripe group.

MODIFYING FILE SYSTEM JOURNAL CONFIGURATION

cvupdatefs will also detect changes in the journal configuration and modify the metadata accordingly. Journal changes include moving the journal to a new stripe group and increasing or decreasing the size of the journal.

JournalSize
(Located in the Global section) Modifying this value will change the size of the on-disk journal.
Journal
(Located in the Stripe Group section) Setting this entry to yes will place the on-disk journal on the given stripe group.

NOTE:

There may only be one journal stripe group per file system.

REMOVING A JOURNAL-ONLY STRIPE GROUP

For Linux MDCs, if a stripe group has only the journal attribute, i.e. no metadata and no userdata, and the journal is moved to another stripe group, the former journal-only stripe group is left with no attributes pertaining to content type. If it is desired that this stripe group be retired and the disks used for other purposes, you can set the status to down after the journal is moved. Note that the status must be up during the journal move operation because the journal recovery must be executed prior to moving the journal.

The behavior is similar on Windows MDCs, except that there is no explicit userdata attribute in the ASCII config file. This means that with no journal and no metadata, userdata is assumed. If the desire is to retire the former journal-only stripe group, care should be taken to not run the file system after moving the journal off of the stripe group. Set the status to down immediately after moving the journal and before starting the FSM.

CORRECTING MISCONFIGURED STRIPE GROUPS

cvupdatefs has a limited ability to address configuration errors. For example, if a stripe group was added but the configuration file shows incorrect disk sizes, this option could be used to rewrite that stripe group. Metadata and Journal stripe groups cannot be rewritten. In addition, data only stripe groups that may be overwritten must be empty.

The types of changes that can be made to a stripe group are as follows

    1) Resize disk definitions in a stripe group
    2) Modify stripe breadth in a stripe group
    3) Modify the disk list in a stripe group

Warning: Always use this option with extreme caution. Configuration errors could lead to data loss.

RENAMING A FILE SYSTEM

Warning: Renaming a file system is only allowed on an unmanaged file system. If cvupdatefs(8) detects that the file system is managed, it will print an error message and exit without doing the rename.

The -R option for renaming an unmanaged file system should be used with care, as there are several things that get modified as part of this process. Before renaming a file system, it is highly recommended that cvfsck(8) be run prior to renaming the file system. The file system must be unmounted on all SAN and DLAN clients, and the file system stopped, see cvadmin(8). If a client has the file system mounted when it is renamed, the client might need to be rebooted in order to unmount the old file system name. On Windows, use the Client Configuration Tool to unmount file system before renaming it.

The unmanaged file system that is being renamed will have been configured in one of three modes: non-HA, HA or manual HA, and how it was configured will change how to rename the file system.

Non-HA mode
There are no extra steps needed when renaming an unmanaged file system that is not in HA mode.
HA mode
When the unmanaged file system is being used in HA mode, prior to running the rename command on the primary, on the secondary the /usr/cvfs/data/FsName directory should be manually renamed to /usr/cvfs/data/NewFsName. When the rename command is then run on the primary, the HA sync processes will propagate all the other configuration changes to the secondary. Wait for the HA sync to complete before continuing.
Manual HA mode
In manual HA mode, the rename command should be run on both MDCs. When run on the second MDC, cvupdatefs(8) will recognize that the name in the ICB has been changed, but will proceed if NewFsName is the same as the name in the ICB. In manual HA mode there is no need to manually rename /usr/cvfs/data/FsName since that will happen as part of running cvupdatefs -R on the second MDC.

After changing the name of a file system, the change will need to be manually reflected in the /etc/fstab, /etc/vfstab or /etc/vstab files on all the clients before they remount the file system. Windows StorNext SAN and DLAN Clients mounts will need to be remapped. Run the Client Configuration Tool to re-map the mount with new file system name.

For any client that is operating as a StorNext File System Proxy Client, check to see if it has a /usr/cvfs/config/dpserver.FsName file. If it does, it will need to be renamed to /usr/cvfs/config/dpserver.NewFsName.

If something goes wrong during the rename operation, cvupdatefs(8) will revert any partial changes, but it is still possible that in some corner cases it will not be able to fully revert the changes, and manual intervention will be required. Files that are modified and/or renamed during the rename operation include:
/usr/cvfs/data/FsName
/usr/cvfs/data/NewFsName
/usr/cvfs/config/FsName.cfgx
/usr/cvfs/config/NewFsName.cfgx
/usr/cvfs/config/fsmlist
as well as the ICB in the file system itself. The OS dependent files that need to be manually updated include:
/etc/fstab
/etc/vfstab
/etc/vstab
Windows registry via the Windows Client Configuration Tool

ENABLING CASE INSENSITIVE

If a change in the file system configuration is detected such that case insensitive is being enabled, cvupdatefs invokes cvfsck as a sub-process to check for name collisions. If name collisions are detected, the update operation will be aborted. It is strongly recommended that cvfsck -A be run prior to attempting the change using cvupdatefs.

EXIT VALUES

cvupdatefs will return one of the following condition codes upon exit.

        0 - No error, no changes made to the file system
        1 - No error, changes have been made to the file system
        2 - Configuration or file system state error, no changes made
        3 - ICB error, improper file system found, no changes made
        4 - Case conversion found name collisions, no changes made

NOTES

IMPORTANT: It is highly recommended to run cvfsck(8) prior to making any configuration changes.

FILES

/usr/cvfs/config/*.cfgx
/usr/cvfs/data/<file_system_name>/config_history/*.cfgx.<TIMESTAMP>

SEE ALSO

snfs_config(5), cvfsck(8), cvadmin(8)