Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

CVUPDATEFS(1)                                                                                  CVUPDATEFS(1)



NAME
       cvupdatefs - Commit a Xsan Volume configuration change

SYNOPSIS
       cvupdatefs [-bdfFhlnSv] [-c pathname]

       [-O ofilename] [-R NewVolName] [VolName] [VolPath]

DESCRIPTION
       The cvupdatefs program is used to commit a configuration change to a Xsan volume. Possible configura-tion configuration
       tion changes include storage pool list modification as well as volume journal modification.

       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.

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

USAGE
       -b     Build info - log the build information.

       -c     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 volume meta data is consis-tent consistent
              tent prior to doing a capacity or bandwidth expansion, or any journal changes.

       -C     Like the -c option, but also instructs cvfsck to check the file  system  for  name  collisions
              that would occur on a case-insensitive file system.

       -d     Debug - use to turn on internal debugging only.

       -F     Force  - do not prompt for confirmation before making changes. WARNING: Errors in the configu-ration configuration
              ration file may cause unintended results.

       -f     Failure mode - do not fail if there is a configuration mismatch.  Note:  This  option  is  not
              intended  for general use.  Use only if instructed by Apple support.  Incorrect use may result
              in an unusable file system.


       -h     Help - print the synopsis for this command.


       -l     Log - log when the update finished.

       -n     Read-only - set metadata to read-only mode.

       -O path_to_original_configuration_file
              Overwrite - This option is required if the configuration changes that  will  be  applied  will
              trigger an overwrite of an existing storage pool. This option should be used with extreme cau-tion. caution.
              tion. Errors in the configuration file could lead to data loss. See the CORRECTING  MISCONFIG-URED MISCONFIGURED
              URED STORAGE POOLS section.

       -R NewVolName
              Rename  - Provide a new volume name to rename an existing unmanaged volume.  The existing con-fig config
              fig 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     Status - write status plist to /var/run/cvupdatefs_status_<FS>.plist.

       -v     Verbose - turn on verbose reporting methods.

       Once  the  volume  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  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.

       Once  the  utility  has  completed,  the  volume may be started again. After starting the volume, the
       'show' command in cvadmin(1) 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'.

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.

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 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  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. cvupdatefs will abort if a new storage
       pool is detected anywhere but the end of the file.

INCREASING BANDWIDTH OF AN EXISTING STORAGE POOL
       Warning: This option is not recommended for capacity expansion. This  option  is  intended  only  for
       increasing I/O parallelism.

       Warning:  When  a storage pool is populated with file data, adding bandwidth will increase fragmenta-tion fragmentation
       tion 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.  The cvup-datefs cvupdatefs
       datefs utility attempts to determine whether the requested bandwidth expansion operation will  intro-duce introduce
       duce unacceptably high fragmentation.  If the level is determined to be unacceptable then the request
       is rejected and cvupdatefs exits with status 2.  Therefore, it is  usually  recommended  to  relocate
       pre-existing file data to a different storage pool prior to performing bandwidth expansion.  If band-width bandwidth
       width expansion is performed without relocating pre-existing file data then it is recommended to uti-lize utilize
       lize snfsdefrag (with the '-d' switch) to correct fragmentation after completion of cvupdatefs.

       If bandwidth is 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.

       Bandwidth  expansion  can never be utilized for a storage pool containing metadata or journal.  Since
       storage pool zero always contains metadata it is not possible to perform bandwidth expansion on stor-age storage
       age pool zero.

       WARNING: Configuration errors may result in data loss.

MODIFYING VOLUME 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 storage pool, increasing the size of  the  jour-nal, journal,
       nal, and reducing the size of the journal.

       JournalSize
              (Located in the Global section) Modifying this value will change the size of the on-disk jour-nal. journal.
              nal.

       Journal
              (Located in the Storage Pool section) Setting this entry to yes will place the on-disk journal
              on the given storage pool.

CORRECTING MISCONFIGURED STORAGE POOLS
       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.

       The types of changes that can be made to a storage pool are as follows

              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
       When making changes to a configuration file to fix a configuration issue, the original  configuration
       file  must  be kept as well.  This file must be passed in to cvupdatefs, using the -O option, so that
       the layout of the existing configuration can be checked.  The -O argument is necessary when  attempt-ing attempting
       ing to overwrite an existing storage pool.

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

NOTE:
       There may only be one journal storage pool per volume.

RENAMING A VOLUME
       Warning: Renaming a volume is only allowed on an unmanaged volume.  If cvupdatefs(1) detects that the
       volume is managed, it will print an error message and exit without doing the rename.

       The  -R option for renaming an unmanaged 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
       cvfsck(1)  be  run  prior  to  renaming the volume.  The volume must be unmounted on all SAN and DLAN
       clients, and the volume stopped, see cvadmin(1).  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.

       The unmanaged 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.

       Non-HA mode
              There are no extra steps needed when renaming an unmanaged volume that is not in HA mode.

       HA mode
              When the unmanaged volume is being used in HA mode, prior to running the rename command on the
              primary, on the secondary the /Library/Logs/Xsan/data/VolName  directory  should  be  manually
              renamed  to  /Library/Logs/Xsan/data/NewVolName.   When  the rename command is then run on the
              primary, the HA sync processes will propagate all the other configuration changes to the  sec-ondary. secondary.
              ondary.  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(1) will recognize that the name in the ICB has been changed, but  will  proceed  if
              NewVolName is the same as the name in the ICB.  In manual HA mode there is no need to manually
              rename /Library/Logs/Xsan/data/VolName since that will happen as part of running cvupdatefs -R
              on the second MDC.

       After changing the name of a volume, 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 volume.  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  an  Xsan  volume  Proxy  Client,  check  to  see  if  it  has  a
       /Library/Preferences/Xsan/dpserver.VolName  file.   If  it  does,  it  will  need  to  be  renamed to
       /Library/Preferences/Xsan/dpserver.NewVolName.

       If something goes wrong during the rename operation, cvupdatefs(1) 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:
          /Library/Logs/Xsan/data/VolName
          /Library/Logs/Xsan/data/NewVolName
          /Library/Preferences/Xsan/VolName.cfg
          /Library/Preferences/Xsan/NewVolName.cfg
          /Library/Preferences/Xsan/fsmlist
       as  well  as  the  ICB in the volume 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

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

               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

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

FILES
       /Library/Preferences/Xsan/*.cfg

SEE ALSO
       snfs_config(5), cvfsck(1), cvadmin(1)



Xsan Volume                                     January 2010                                   CVUPDATEFS(1)