statfs.txt

   1 Statfs
   2 ~~~~~~
   3
   4 The 'statfs' VFS method queries file-system-wide space and inode
   5 usage. For details about the MDS_STATFS RPC, including possible faults
   6 and error return codes, see <<mds-statfs-rpc>>, and for OST_STATFS see
   7 <<ost-statfs-rpc>>.
   8
   9 A client gets 'statfs' information for the file system as a whole by
  10 first querying the individual storage targets for the 'statfs'
  11 information on each back-end file system. The RPCs that flow are as
  12 shown in <<statfs-rpcs>>. The values returned in the VFS call are
  13 built from the results of the *_STATFS RPCs as follows:
  14
  15 .Statfs values
  16 [options="header"]
  17 |====
  18 | field       | VFS value
  19 | 'f_type'    | 0x0bd00bd0
  20 | 'f_bsize'   | OST 'os_bsize'
  21 | 'f_blocks'  | sum over OSTs 'os_blocks'
  22 | 'f_bfree'   | sum over OSTs 'os_bfree'
  23 | 'f_bavail'  | sum over OSTs 'os_bavail'
  24 | 'f_files'   | sum over MDTs 'os_ffiles'
  25 | 'f_ffree'   | sum over MDTs 'of_ffree'
  26 | 'f_fsid'    | UUID
  27 | 'f_namelen' | maximum filename length
  28 |====
  29
  30 See the discussion in <<struct-obd-statfs>> for details about the
  31 'obd_statfs' fields 'os_*'. In particular, the total and free objects
  32 counts would normally be determined by the corresponding values on the
  33 MDTs, but if the total objects available across all OSTs (respectively
  34 free objects) happens to be fewer than the number on the MDTs, then
  35 the smaller value is used.  The number of free objects is modified as
  36 described below to ensure that at least this many new files can be
  37 created.  The total number of objects is changed to preserve the
  38 difference 'f_files' - 'f_ffree', which is the current number of
  39 used objects. This is what "df" displays.
  40
  41 The number of OST free objects is divided by the filesystem-wide
  42 default stripe count (i.e. the expected number of OST objects used per
  43 MDT file), so that 'f_ffree' represents the expected minimum number of
  44 files that can be created at the current time.
  45
  46 The 'os_{bfree,bavail,blocks}' values are scaled down (in power-of-two
  47 increments) to match the maximum 'os_bsize' returned from any OST so
  48 that the sum of these fields makes sense, and potentially scaled down
  49 again (also in power-of-two increments) to increase 'f_bsize' to fit
  50 into the 'statfs' structure so that the 'f_blocks' field will fit into the
  51 available field width (which may only be 2^32 blocks on a 32-bit
  52 client).
  53
  54 For most possible error conditions directly related to processing
  55 'statfs' information (ENOMEM, for instance) the error is propagated
  56 back to the VFS and the 'struct statfs' does not have valid
  57 information. In the case of an EAGAIN during an exchange of RPC
  58 messages, that error is handled transparently to the 'statfs' itself.
  59
  60 .Statfs RPCs
  61 [[statfs-rpcs]]
  62 image::statfs_rpcs.png["statfs RPCs",height=150]
  63
  64 //////////////////////////////////////////////////////////////////////
  65 The statfs_rpcs.png diagram resembles this text art:
  66
  67 Time
  68 Step Client         MDT          OST
  69      -------        -------      -------
  70 1    MDS_STATFS------>
  71 2             <------MDS_STATFS
  72 3    OST_STATFS------>
  73 4             <------OST_STATFS
  74 //////////////////////////////////////////////////////////////////////
  75
  76 *1 - The client issues an MDS_STATFS request to each MDT.*
  77
  78 The MDS_STATFS request is a so-called 'empty' RPC in that it consists
  79 only of the 'ptlrpc_body' (Lustre RPC descriptor) with the opcode set to
  80 MDS_STATFS (41). Refer to the discussion of <<mds-statfs-rpc>> for
  81 more general information about the MDS_STATFS RPC's request and reply
  82 messages.
  83
  84 .MDS_STATFS Request Packet Structure
  85
  86 :frame: none
  87 :grid: none
  88 [width="50%", cols="2a"]
  89 |====
  90 | request
  91 [cols="1"]
  92 !===================
  93 ! <<struct-ptlrpc-body,ptlrpc_body>> !
  94 !===================
  95 |====
  96
  97 *2 - The MDS_STATFS reply returns 'statfs' info*
  98
  99 In addition to the 'ptlrpc_body' (Lustre RPC descriptor), the
 100 MDS_STATFS reply to the client has the 'obd_statfs' structure. For a
 101 detailed discussion of the fields in the 'obd_statfs' refer to
 102 <<struct-obd-statfs>>.
 103
 104 .MDS_STATFS Reply Packet Structure
 105
 106 :frame: none
 107 :grid: none
 108 [width="50%", cols="2a"]
 109 |====
 110 | reply
 111 [cols="2"]
 112 !===================
 113 ! <<struct-ptlrpc-body,ptlrpc_body>> ! <<struct-obd-statfs,obd_statfs>> !
 114 !===================
 115 |====
 116
 117 *3 - The client issues an OST_STATFS request to each OST.*
 118
 119 The OST_STATFS RPC looks just like the MDS_STATFS, except the opcode
 120 is 13 instead of 41 and the target of the RPC is an OST instead of an
 121 MDT.
 122
 123 .OST_STATFS Request Packet Structure
 124
 125 :frame: none
 126 :grid: none
 127 [width="50%", cols="2a"]
 128 |====
 129 | request
 130 [cols="1"]
 131 !===================
 132 ! <<struct-ptlrpc-body,ptlrpc_body>> !
 133 !===================
 134 |====
 135
 136
 137 *4 - The OST_STATFS reply returns 'statfs' info*
 138
 139 In addition to the 'ptlrpc_body' (Lustre RPC descriptor), the OST_STATFS
 140 reply to the client has the 'obd_statfs' structure. For a detailed
 141 discussion of the fields in the 'obd_statfs' refer to
 142 <<struct-obd-statfs>>.
 143
 144 .OST_STATFS Reply Packet Structure
 145
 146 :frame: none
 147 :grid: none
 148 [width="50%", cols="2a"]
 149 |====
 150 | reply
 151 [cols="2"]
 152 !===================
 153 ! <<struct-ptlrpc-body,ptlrpc_body>> ! <<struct-obd-statfs,obd_statfs>> !
 154 !===================
 155 |====