manpagez: man pages & more
man cvupdatefs(1)
Home | html | info | man
cvupdatefs(1)                                                    cvupdatefs(1)


       cvupdatefs - Commit a Xsan Volume configuration change


       cvupdatefs [-bdfFhlnSv] [-c pathname]

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


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

       The volume update program must be run on the machine that the File Sys-
       tem 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 configura-
       tion  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.   Maintaining  a
       backup  of the original volume configuration file is also strongly rec-


       -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  consistent
              prior to doing a capacity or bandwidth expansion, or any journal

       -C     Like the -c option, but also instructs cvfsck to check the  file
              system  for  name collisions that would occur on a case-insensi-
              tive 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 configuration file may cause unintended

       -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 caution.
              Errors in the configuration file could lead to  data  loss.  See

       -R NewVolName
              Rename  - Provide a new volume name to rename an existing unman-
              aged volume.  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     Status   -   write   status  plist  to  /var/run/cvupdatefs_sta-

       -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 cvup-
       datefs 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'.


       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  exe-
       cuted  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.


       The  first  step in adding storage pools is to modify the volume's con-
       figuration 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 configu-
       ration  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.


       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  band-
       width  will  increase fragmentation of the storage pool proportional to
       the amount of pre-existing file data.  It is important to  avoid  frag-
       mentation,  which severely impacts performance and functionality of the
       volume.  The cvupdatefs  utility  attempts  to  determine  whether  the
       requested  bandwidth  expansion  operation  will introduce 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  dif-
       ferent  storage pool prior to performing bandwidth expansion.  If band-
       width expansion is performed without relocating pre-existing file  data
       then  it is recommended to utilize 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  sec-

       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 storage pool zero.

       WARNING: Configuration errors may result in data loss.


       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 journal,  and
       reducing the size of the journal.

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

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


       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

       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  lay-
       out  of  the existing configuration can be checked.  The -O argument is
       necessary when attempting to overwrite an existing storage pool.

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


       There may only be one journal storage pool per 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 cvf-
       sck(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 vol-
              ume 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 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(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  manu-
       ally  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 Con-
       figuration 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/Prefer-

       If something goes wrong during the rename operation, cvupdatefs(1) will
       revert any partial changes, but it is still possible that in some  cor-
       ner  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:
       as  well  as the ICB in the volume itself.  The OS dependent files that
       need to be manually updated include:
          Windows registry via the Windows Client Configuration Tool


       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


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




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

Xsan Volume                      January 2010                    cvupdatefs(1)

Mac OS X 10.9.1 - Generated Sun Jan 5 12:51:31 CST 2014
© 2000-2021
Individual documents may contain additional copyright information.