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




NAME

       snquota - Xsan Quota Configuration Utility


SYNOPSIS

       snquota {-F volume_name|-P path} action [options]


DESCRIPTION

       The snquota command manipulates the quota system in the Xsan volume.

       The quota system provides a means for limiting the amount of disk stor-
       age consumed on a per user or per group basis  across  an  entire  file
       system  or within a designated directory hierarchy.  Quota limits apply
       to the space consumed by disk-block allocations for a  user  or  group,
       which  is not equal to the sum of their file sizes.  Disk-block alloca-
       tions can be less than the file size if the file is sparse, or more  if
       the file system has allocated extra sequential blocks for the efficien-
       cy of anticipated future writes.

       There are three types of quotas: user quotas, group quotas, and  direc-
       tory  quotas.   User and group quotas limit the number of volume blocks
       that can be allocated by the user  or  group  on  which  the  limit  is
       placed.   When  quotas  are on, the total allocated volume space of all
       users and groups that own files in the volume are automatically kept.

       Directory quotas are a little different.  The system does not automati-
       cally  keep track of the usage for each directory.  The snquota command
       allows directories to be turned into the root of a Directory Quota Name
       Space  (DQNS).  Then, the number and size of all files in the directory
       and all its subdirectories are tracked and (optionally) limited.

       For all quota types, limits and usage  values  only  apply  to  regular
       files, not directories, symlinks, or special device files

       Each  quota  entity  has  two limits associated with it.  These are the
       hard limit and the soft limit.

       The hard limit is the absolute limit which volume  space  usage  should
       not  exceed.  Any time the total allocated space is at or over the hard
       limit, all further allocations or write requests by the offending  user
       or group will be denied.

       The  soft  limit  is  a lesser limit.  When the user exceeds this limit
       (but not the hard limit), allocations are still permitted for a  while,
       but  a warning message will be written to the logs.  (View the messages
       with Console.app or the dmesg command.)  When the soft limit  has  been
       overrun for longer than the grace period, the soft limit becomes a hard
       limit and any further allocations or write requests are  denied.   When
       the  usage  again  falls below the soft limit, allocation requests will
       again be serviced.

       When the hard limit, soft limit, and grace period are all zero, no lim-
       its  are  enforced  for  that quota.  If any of the three are zero, all
       three must be zero.

       For performance reasons related to the distributed nature of Xsan, quo-
       ta overruns are not only possible but likely.  The overrun size depends
       upon a number of factors including  the  size  of  the  allocation  re-
       quest(s) at the time of the quota overrun.

       When working with Directory Quotas, the specified volume must be mount-
       ed on the node running snquota.

       Limits are not enforced against super user accounts.


DIRECTORY QUOTA NAME SPACES

       DQNSs are created by either of two actions, -C or -M.  They  have  dif-
       ferent performance trade-offs and which one to use depends on the situ-
       ation at hand.

       The -C action creates a DQNS whose usage values  (the  amount  of  disk
       space  and  the number of files) are already initialized to the correct
       value.  In order to initialize them, snquota must  walk  the  directory
       tree  under  the  root  of the DQNS and tally up how much disk space is
       used.  For big directory trees, this process can take a long time.  Any
       modifications  to the files and directories in the DQNS will be stalled
       until this walk is complete.

       The -M action quickly creates a DQNS whose usage values are  zero.   As
       files  are created in the DQNS, the usage value will increase, but will
       never count the files that were present in the directory  when  it  was
       created.   In  order  to initialize the DQNS so the values are correct,
       the quota database must be rebuild using the -R action.  A rebuild runs
       much  faster  than  a  file-tree walk on a per-inode basis, but it must
       look at all of the inodes in the volume.  When the rebuild is  running,
       modifications  to  the volume will be stalled until the rebuild is com-
       plete.

       So, when creating a DQNS that is believed to contain only a small  per-
       centage  of the inodes in the volume, use -C.  When creating a DQNS (or
       many DQNSs) that use a large percentage of the files, use -M.

       A typical situation where -M would be useful is converting an  existing
       volume  to  use directory quotas.  First every directory which needs to
       be a DQNS root is marked with a call to "snquota -M".  Then, all of the
       DQNSs are initialized with one call to "snquota -R".

       When in doubt, use -C.

       Nesting  of  DQNSs is not allowed.  This means that a DQNS may not be a
       subdirectory of another DQNS.

       Directories can not be renamed across DQNS boundaries.  Also, all  hard
       links to an inode must be within the same DQNS.  Attempts to rename di-
       rectories/files or create hard links that would violate this rule  will
       result in a EXDEV being returned.

       If  a  directory  tree  contains  inodes with hard links outside of the
       tree, an attempt to convert the tree into a DQNS via the -C  action  on
       the  tree will result in an error.  An attempt to convert the tree into
       a DQNS via the -M and -R actions will result in an error during the  -R
       action.


QUOTAS IN MIXED OS ENVIRONMENTS

       The  user  and groups names specified in -u and -g represent underlying
       identifiers that are determined by the OS type of the MDC.

       On a Linux or Xsan MDC, those identifiers are  the  classic  UNIX  User
       IDentifier  (UID) and Group IDentifier (GID).  When a UNIX client (Lin-
       ux, MacOS, Solaris, etc) creates a file, it passes the user's  UID  and
       GID to the MDC.  Those IDs are attached to the file and are used by the
       quota subsystem.  When a Windows client creates a file, it passes a UID
       and GID it gets from one of three places:


       1.     If  the Active Directory entry for the user has UNIX IDs associ-
              ated with it, those are used.  The behavior  at  this  point  is
              just  like UNIX client.  The administrator can set the IDs for a
              user via the AD configuration tool under the  "UNIX  Attributes"
              tab.   This  tab  is  part of the "Identity Management for UNIX"
              subsystem.

       2.     If the user doesn't have UNIX  attributes,  then  the  user  and
              group  "nobody"  IDs from the file system configuration file are
              used.

       3.     If the process's SID is a special "Root SID", the UID/GID passed
              will be 0/0 (i.e. root).  The "root SID" is S-1-5-18.

       The  Windows  client can associate a NTSD with a file, but it's ignored
       by the quota subsystem. (It's only  used  for  access  control  by  the
       client at that point.)

       On  a  Windows MDC, the favored identifiers are user and group SIDs de-
       rived from the NTSD which owns the file.  If there is no NTSD associat-
       ed  with  the  file,  the  UID/GID values associated with the inode are
       used.  So, when a Windows client creates a file, it passes in  a  NTSD.
       That  NTSD broken into SIDs and used as file's owner identifiers as far
       as the quota subsystem is concerned.  When  a  UNIX  client  creates  a
       file,  it  passes  the usual UID/GID pair, not a NTSD.  This is used by
       the quota system.  If that file is accessed from a on  Windows  client,
       it gets assigned an NTSD.  At that point the quota will be wrong.  Sub-
       sequent allocations of that file will be charged to the SD and not  the
       UID/GID.

       So,  the  preferred method of running quotas with a mixture of UNIX and
       Windows clients is to run with a Linux MDC with  UNIX  user/group  map-
       pings  for  Active  Directory  users.   That  way, a user who logs into
       clients of either OS will have a single quota (which will be  based  on
       the UID).

       Another  option  is  to  just use Directory Quotas.  They are much more
       straight-forward to share between OS types.


UNITS

       Usage and Limits are printed in a human-readable  form,  suffixed  with
       "K",  "M",  "G",  "T", or "P" for kilobytes, megabytes, gigabytes, ter-
       abytes, or petabytes (respectively).  These are base-2 values (i.e.  1K
       = 1024).  A value without a suffix is in bytes.

       File  count  values  are also printed with these suffixes, but they are
       base-10 values (i.e. 1K = 1000).

       Time values are printed with the suffixes "m", "h", "d", "w",  "M"  and
       "y" for minutes, hours, days, weeks, months and years (respectively).

       If  the  -e  option is used, the suffixes are disabled and exact values
       are printed. Time units are in minutes.

       These suffixes can also be used when specifying limits with the -h, -s,
       and -t options.  Decimal values may be used (e.g -h 1.5g).  The case of
       the suffix doesn't matter.


FILE SYSTEM SPECIFICATION

       -F VolumeName
              Specify VolumeName as the volume to manipulate.

       -P Path
              Specify the volume containing Path as the volume to  manipulate.


ACTIONS

       -C     This  action creates an initialized DQNS on the directory speci-
              fied by the -d argument.  After this command is run, disk  space
              usage  and  file counts will be tracked in the directory and all
              its subdirectories.  Later, limits may be set on the DQNS  using
              the  -S action.  Note that since this operation creates and ini-
              tializes the DQNS, the directory tree contained by the new  DQNS
              will  be  walked to total up the current usage values.  This may
              take some time.  Modifications to the files and  directories  in
              the DQNS will be stalled until this walk is complete.

       -D     This  action  destroys  the  DQNS  specified by the -d argument.
              Disk space and  file  count  usage  values  will  no  longer  be
              tracked.   Limits  will  no  longer be enforced.  Note that this
              does not modify or destroy the files and directories in the DQNS
              in any way.

       -G     This  action  returns  the quota limits and values for the user,
              group, or directory specified by the -u, -g, or -d  option  (re-
              spectively).

       -L     This  action  lists  the current quota limits and values for all
              user, group, and directory quotas.

       -M     This action creates (marks) an uninitialized DQNS on the  direc-
              tory  specified  by the -d argument.  After this command is run,
              disk space usage and file counts will be tracked in the directo-
              ry  and all its subdirectories.  Later, limits may be set on the
              DQNS using the -S option.  Note that since this  operation  cre-
              ates  (but  does  not initialize) the DQNS, the usage values for
              the DQNS will start out at zero.  The user should later use  the
              -R  action  to  initialize  the usage values.  See the DIRECTORY
              QUOTA NAME SPACES section above for a discussion on when to  use
              -M  and  when  to use -C.  When in doubt, don't use this action.
              Use -C instead.

       -R     This action rebuilds the quota database.  It is most useful when
              used  after  snquota has been used a number of times with the -M
              action.  See the DIRECTORY  QUOTA  NAME  SPACES  section  above.
              Note  that this action can take a long time.  The volume will be
              unresponsive during this time.  The action  cannot  be  canceled
              after  it is started.  A prompt will be displayed confirming the
              intent to run the action unless the -Y option  is  specified.  A
              rebuild preserves limits and DQNSs.

       -S     This action sets the quota limits for the user, group, or direc-
              tory specified by the -u, -g, or -d option (respectively).   The
              limits  must  be  specified by the -h, -s, and -t, options.  All
              three must be present.

       -X     This action generates quota reports for all  users  and  groups.
              There  are  three  files placed in /Library/Logs/Xsan/data/<vol-
              ume_name>:
                  1. quota_report.txt - a "pretty" text file report.
                  2. quota_report.csv - a comma delimited report suitable
                     for Excel spreadsheets.
                  3. quota_regen.in - a list of snquota commands that can
                     be used to set up an identical quota database on another
                     Xsan volume. Redirecting this file
                     to the shell executes this as a script.

       -Z     This action resets and then rebuilds the quota  database  as  in
              the  -R option above. Unlike the  -R action,  -Z clears the lim-
              its and DQNSs but they can be  restored  from  a  quota.regen.in
              file.


OPTIONS

       -a     When  this  option is used, directory quota paths printed by the
              -L and -G options will be absolute paths.  Paths supplied to the
              -d  option  are  also  absolute  paths (or relative to the CWD).
              When this option is absent, all paths are relative to  the  root
              of the specified volume.

       -d Directory
              This  option  specifies  a DQNS on a Xsan volume to be used with
              the -C, -D, -G, -M, or -S options.  The  directory  supplied  is
              the  root directory of the DQNS.  The directory path is relative
              to the root of the specified volume, unless  the  -a  option  is
              used.

       -e     When  used with the -G or -L actions, numbers will be printed as
              exact values.  Usage and Limits which represent disk  space  are
              printed  in  bytes.  Times are printed in minutes.  For example,
              with this option, a one megabyte hard limit will be  printed  as
              "1048576",  not "1M".  A one day grace period will be printed as
              "1440", not "1d".

       -f     The -f option is only useful with the -G and -S actions and  the
              -d  option.   When  the  -f option is present, limits and values
              represent the number of regular files contained in the DQNS.  If
              the  -f  option  is not present, limits and values represent the
              disk space contained in the DQNS.

       -g GroupName
              This option specifies the name of a group to get or set with the
              -G or -S action.  The group name may also be of the form "G:id",
              where "id" is a number that represents a group's GID.

       -H HostName
              Use a hostname in a Xsan cluster  that  is  different  from  the
              cluster  the  command  is  being  run on.  This option in rarely
              needed.

       -h HardLimit
              This option specifies a hard limit to set when used with the  -S
              action.  See the UNITS section above.

       -h     This  option causes snquota to print a friendly help message and
              exit.  It only works when used by itself.  If  there  are  other
              options present, it is assumed that a hard limit is being speci-
              fied.

       -o {text|xml|json}
              Print output in text, xml, or json.  The default is text.

       -s SoftLimit
              This option specifies a soft limit to set when used with the  -S
              action.  See the UNITS section above.

       -t GracePeriod
              This  option  specifies a grace period to set when used with the
              -S action.  See the UNITS section above.

       -u UserName
              This option specifies the name of a user to get or set with  the
              -G  or -S action.  The user name may also be of the form "U:id",
              where "id" is a number that represents a user's UID.

       -Y     When used with the -R action, this option prevents snquota  from
              asking for confirmation.

       -z     This  option  is  the same as specifying "-h 0 -s 0 -t 0".  It's
              only useful with the -S action.


EXIT VALUES

       snquota will return 0 on success and non-zero on failure.


EXAMPLES

       List all the quota limits and values on a volume named "data".

          snquota -F data -L

       Specify a hard limit of ten gigabytes, a soft limit of nine  gigabytes,
       and a grace period of one week on user "lisa" in a volume named "data".

          snquota -F data -S -u lisa -h 10g -s 9g -t 1w.

       Turn off quota limits for user "lisa" in a volume named "data".

          snquota -F data -S -u lisa -z.

       Get the quota values for a group named "simpsons" on a  volume  mounted
       on "/stornext/data".

          snquota -P /stornext/data -G -g simpsons

       Create  a  DQNS  on  the  directory "/lisa/saxophone_music" in a volume
       mounted on "/stornext/data".

          snquota -P /stornext/data -C -d /lisa/saxophone_music

       Specify a hard limit of one gigabyte, a  soft  limit  of  nine  hundred
       megabytes,  and  a  grace  period  of  one  day  on  pre-existing  DQNS
       "/lisa/saxophone_music" in a volume named "data".

          snquota -F data -S -d /lisa/saxophone_music -h 1g -s 900m -t 1d.

       Create a number of DQNSs using -M and -R.  This is faster than using -C
       if these directories take up most of the space in the volume.

          snquota -F data -M -d /bart/comics
          snquota -F data -M -d /bart/pranks
          snquota -F data -M -d /bart/itchy_and_scratchy
          snquota -F data -R

       Create the same DQNSs using -C.  This is faster than using -M and -R if
       the directories are small.

          snquota -F data -C -d /bart/comics
          snquota -F data -C -d /bart/pranks
          snquota -F data -C -d /bart/itchy_and_scratchy

       Specify a hard limit of one thousand files, a soft limit of  nine  hun-
       dred  files,  and  a  grace  period  of  one  week on pre-existing DQNS
       "/bart/pranks" in a volume named "data".

          snquota -F data -S -d /bart/pranks -f -h 1k -s 900 -t 1w.


SEE ALSO

       cvadmin(8), snfs_config(5)



Xsan File System                   June 2015                        snquota(1)

Mac OS X 10.12.3 - Generated Sat Feb 4 18:17:14 CST 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.