.\" cvupdatefs.8: auto-generated, DO NOT EDIT .\" .\" Copyright 2002-2021. Quantum Corporation. All Rights Reserved. .\" StorNext is either a trademark or registered trademark of .\" Quantum Corporation in the US and/or other countries. .\" .\" Code start macro .de Cs .sp .ft C .in +0.3i .nf .. .\" Code end macro .de Ce .fi .in -0.3i .ft R .. .TH CVUPDATEFS 8 "November 2021" "Xsan Volume" .SH NAME cvupdatefs \- Commit a Xsan Volume configuration change .SH SYNOPSIS .na .nh .HP .B cvupdatefs .RB [ -bdfFhlnSv ] .RB [ -c \ \fIpathname\fP] .RB [[ -M ] \ -R \ \fINewVolName\fP] .RI [ VolName ] .RI [ VolPath ] .ad .hy .SH DESCRIPTION The \fBcvupdatefs\fR program is used to commit a configuration change to a Xsan volume. Possible configuration changes include storage pool list modification as well as volume journal modification. .PP The volume 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 volume metadata up to date. .PP .I NOTE: All metadata modification must be made on a stopped volume. It is recommended that the volume is stopped and .BR cvfsck (8) has been run before making any changes to a volume configuration. Maintaining a backup of the original volume configuration file is also strongly recommended. .PP When a successful update is completed, the new configuration file is stored in the on-disk metadata and the previous one is saved in .IR /Library/Logs/Xsan/data/ /config_history/*.cfg. .SH OPTIONS .IP \fB\-b\fR Build info - log the build information. .IP "\fB-c\fP \fIpathname\fP" Provide a specific path to the previous configuration file that is to be used. This option is used to force \fBcvfsck\fR to be run as a sub-process to insure that the volume meta data is consistent prior to doing a capacity or stripegroup expansion, or any journal changes. .IP \fB-d\fR Debug - use to turn on internal debugging only. .IP \fB-F\fR Force. This option has been deprecated and replaced with \fB-y\fR. It will cause the same action as that option. .IP \fB-f\fR Failure mode - do not fail if there is a configuration mismatch or other serious abnormal condition detected. Note: This option is \fBnot\fR intended for general use. Use only if instructed by Apple support. Incorrect use may result in an unusable file system. .TP .BI \fB\-h\fR Help - print the synopsis for this command. .IP \fB-l\fR Log - log when the update finished. .IP \fB-n\fR Read-only - set metadata to read-only mode. .IP \fB-M\fR Allow managed file systems with -R option. .IP "\fB-R\fP \fINewVolName\fP" Rename - Provide a new volume name to rename an existing unmanaged volume. Use with \fB-M\fR to rename a managed 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. .IP \fB-s\fR Slice rebuild - Rebuild the free slice trees to their optimal sizes. When extending the LUNs in a storagepool, by default it will just add enough additional slices to hold the additional free space. When the \fB-s\fR 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. .IP \fB-S\fR Status - write status plist to /var/run/cvupdatefs_status_.plist. .IP \fB-U\fR When a storagepool is added, do a check for disks that are included in the storagepool 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. .IP \fB\-v\fR Verbose - turn on verbose reporting methods. .IP \fB\-y\fR 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. .IP \fB\-W\fR Do not use copy-on-write (COW) when applying changes. .PP Once the volume configuration has been changed to reflect the stripe group or journal changes the \fBcvupdatefs\fR utility may be run. When \fBcvupdatefs\fR is run it will display a listing of storage pools 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. .PP Once the utility has completed, the volume may be started again. After starting the volume, the 'show' command in .BR cvadmin (8) may be used to verify the new storage pools. The 'show' command will list all of the stripe groups on the volume, including the newly created storage pool(s). Also, if the location of the volume journal has changed this too will be reflected by the cvadmin command 'show'. .SH WARNINGS It is very important that the consistency of the volume be correct before cvupdatefs is run. If the volume has a bad state cvupdatefs could introduce data corruption. It is recommended that cvfsck is executed on the volume before any changes are made. If cvfsck does not finish with a clean volume do not make any configuration changes until the volume is clean. .SH ADDING A STORAGE POOL The first step in adding storage pools is to modify the volume's configuration file to reflect the desired changes. For notes on volume configuration format refer to .BR snfs_config (5). In addition to adding StripeGroup configuration entries, associated Disk and DiskType entries for any new disks must be included. .PP Currently the ordering of storage pools in the configuration file and in the metadata must match. Thus, when adding new storage pool configuration entries to the configuration file they must always be added to the end of the StripeGroup configuration section. \fBcvupdatefs\fR will abort if a new storage pool is detected anywhere but the end of the file. .SH INCREASING THE STRIPE DEPTH OF AN EXISTING STORAGE POOL \fBWarning\fR: 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. .PP The stripe depth is the number of disks in the storage pool and is a key factor in the amount of parallel I/O that can be accomplished. This choice should ideally be made before the volume is created, thus eliminating the need for cvupdatefs to modify this value by adding disks to the storage pool. Consult the StorNext File System Tuning Guide for information on configuring for optimal file system performance. .PP \fBWarning\fR: When a storage pool is populated with file data, adding disks will increase free space fragmentation of the storage pool proportional to the amount of pre-existing file data. It is important to avoid fragmentation, which severely impacts performance and functionality of the volume. If the storage pool 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 storage pool. .PP When new disks are added to an existing storage pool 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. .PP New disks cannot be added to a storage pool containing metadata or journal. A new storage pool 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 storage pool. .PP .SH MODIFYING VOLUME JOURNAL CONFIGURATION .B cvupdatefs will also detect changes in the journal configuration and modify the metadata accordingly. Journal changes include moving the journal to a new storage pool and increasing or decreasing the size of the journal. .IP JournalSize (Located in the Global section) Modifying this value will change the size of the on-disk journal. .IP Journal (Located in the Storage Pool section) Setting this entry to yes will place the on-disk journal on the given storage pool. .SH NOTE: There may only be one journal storage pool per volume. .SH 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. .PP 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. .SH CORRECTING MISCONFIGURED STORAGE POOLS .B cvupdatefs has a limited ability to address configuration errors. For example, if a storage pool was added but the configuration file shows incorrect disk sizes, this option could be used to rewrite that stripe group. Metadata and Journal storage pools cannot be rewritten. In addition, data only storage pools that may be overwritten must be empty. .PP The types of changes that can be made to a storage pool are as follows .Cs 1) Resize disk definitions in a storage pool 2) Modify stripe breadth in a storage pool 3) Modify the disk list in a storage pool .Ce .PP \fBWarning:\fR Always use this option with extreme caution. Configuration errors could lead to data loss. .SH RENAMING A VOLUME .BR Warning : Renaming a volume that is managed requires additional steps documented elsewhere. These are in the StorNext documentation center. When following those instructions, the -M option must be used when invoking this command with the -R option. Otherwise, renaming a volume is only allowed on an unmanaged volume. Without the -M option, if .BR cvupdatefs (8) detects that the volume is managed, it will print an error message and exit without doing the rename. .PP The \fB-R\fR option for renaming a volume should be used with care, as there are several things that get modified as part of this process. Before renaming a volume, it is highly recommended that .BR cvfsck (8) be run prior to renaming the volume. The volume must be unmounted on all SAN and DLAN clients, and the volume stopped, see .BR cvadmin (8). If a client has the volume mounted when it is renamed, the client might need to be rebooted in order to unmount the old volume name. On Windows, use the Client Configuration Tool to unmount volume before renaming it. .PP The volume 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 volume. .TP .B "Non-HA mode" There are no extra steps needed when renaming a volume that is not in HA mode. .TP .B "HA mode" When a volume is being used in HA mode, prior to running the rename command on the primary, on the secondary the \fI/Library/Logs/Xsan/data/\fRVolName directory should be manually renamed to \fI/Library/Logs/Xsan/data/\fRNewVolName. 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. .TP .B "Manual HA mode" In manual HA mode, the rename command should be run on both MDCs. When run on the second MDC, .BR cvupdatefs (8) will recognize that the name in the ICB has been changed, but will proceed if \fINewVolName\fR is the same as the name in the ICB. In manual HA mode there is no need to manually rename \fI/Library/Logs/Xsan/data/\fRVolName since that will happen as part of running \fBcvupdatefs -R\fR on the second MDC. .PP After changing the name of a volume, the change needs to be manually reflected in the \fI/etc/fstab\fR, \fI/etc/vfstab\fR or \fI/etc/vstab\fR files on all the clients before they remount the volume and the corresponding directories renamed or created. 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. .PP For any client that is operating as an Xsan volume Proxy Client, check to see if it has a \fI/Library/Preferences/Xsan/dpserver.\fRVolName file. If it does, it will need to be renamed to \fI/Library/Preferences/Xsan/dpserver.\fRNewVolName. .PP If something goes wrong during the rename operation, .BR 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: .in +0.3i .br .I /Library/Logs/Xsan/data/\fRVolName\fP .br .I /Library/Logs/Xsan/data/\fRNewVolName\fP .br .I /Library/Preferences/Xsan/\fRVolName\fP.cfg .br .I /Library/Preferences/Xsan/\fRNewVolName\fP.cfg .br .I /Library/Preferences/Xsan/fsmlist .in -0.3i .br as well as the ICB in the volume itself. The OS dependent files that need to be manually updated include: .in +0.3i .br .I /etc/fstab .br .I /etc/vfstab .br .I /etc/vstab .br Windows registry via the Windows Client Configuration Tool .in -0.3i .SH ENABLING CASE INSENSITIVE .PP If a change in the file system configuration is detected such that case insensitive is being enabled, \fBcvupdatefs\fR invokes \fBcvfsck\fR 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 \fBcvfsck -A\fR be run prior to attempting the change using \fBcvupdatefs\fR. .SH EXIT VALUES cvupdatefs will return one of the following condition codes upon exit. .Cs 0 - No error, no changes made to the volume 1 - No error, changes have been made to the volume 2 - Configuration or volume state error, no changes made 3 - ICB error, improper volume found, no changes made 4 - Case conversion found name collisions, no changes made .Ce .SH NOTES .I IMPORTANT: It is highly recommended to run .BR cvfsck (8) prior to making any configuration changes. .PP By default, cvupdatefs uses a copy-on-write (COW) store and applies changes to metadata at the very end. This is beneficial for performance and allows easier recovery if any issues are encountered that prevent successful completion. When COW is enabled, temporary space is typically consumed from /tmp or similiar, depending on the platform. However, the temporary directory can be set using the TMPDIR environment variable. As noted above, COW can be disabled using the -W option in which case no temporary space is used. .SH FILES .I /Library/Preferences/Xsan/*.cfg .br .IR /Library/Logs/Xsan/data/ /config_history/*.cfg. .SH "SEE ALSO" .BR snfs_config (5), .BR cvfsck (8), .BR cvadmin (8)