lustre/doc/lfs-getstripe.1

   1 .TH lfs-getstripe 1 "2018-01-24" Lustre "user utilities"
   2 .SH NAME
   3 lfs-getstripe \- Lustre client command to print layout parameters of a file
   4 .SH SYNOPSIS
   5 .B lfs getstripe
   6 [\fB--component-count\fR|\fB--comp-count\fR]
   7       [\fB--component-end\fR|\fB--comp-end\fR|\fB-E\fR[\fB=\fR[\fB+-\fR]\fIEND_OFFSET\fR[\fBKMGTPE\fR]]
   8       [\fB--component-flags\fR|\fB--comp-flags\fR[\fB=\fICOMP_FLAGS\fR]]
   9       [\fB--component-id\fR|\fB--comp-id\fR[=\fICOMP_ID\fR]|\fB-I\fR[\fICOMP_ID\fR]]
  10       [\fB--component-start\fR[\fB=\fR[\fB+-\fR]\fISTART_OFFSET\fR[\fBKMGTPE\fR]]]
  11       [\fB--extension-size\fR|\fB--ext-size\fR|\fB-z\fR]
  12       [\fB--directory\fR|\fB-d\fR]
  13 [\fB--fid\fR|\fB-F\fR]
  14 [\fB--generation\fR|\fB-g\fR]
  15 [\fB--help\fR|\fB-h\fR]
  16 [\fB--hex-idx\fR]
  17       [\fB--layout\fR|\fB-L\fR]
  18 [\fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR]
  19 [\fB--ost\fR|\fB-O\fR \fIOST_NAME\fR]
  20       [\fB--pool\fR|\fB-p\fR]
  21 [\fB--quiet\fR|\fB-q\fR]
  22 [\fB--recursive\fR|\fB-r\fR]
  23       [\fB--raw\fR|\fB-R\fR]
  24 [\fB--stripe-count\fR|\fB-c\fR]
  25 [\fB--stripe-index\fR|\fB-i\fR]
  26       [\fB--stripe-size\fR|\fB-S\fR] [\fB--mirror-count\fR|\fB-N\fR]
  27       [[\fB!\fR] \fB--mirror-index\fR=[\fB+-\fR]\fIMIRROR_INDEX\fR | [\fB!\fR] \fB--mirror-id\fR=[\fB+-\fR]\fIMIRROR_ID\fR]
  28       [\fB--verbose\fR|\fB-v\fR]
  29 [\fB--yaml\fR|\fB-y\fR][\fB--no-follow\fR]
  30 \fIFILENAME\fR|\fIDIRECTORY\fR ...
  31
  32 .SH DESCRIPTION
  33 .nh
  34 .ad l
  35 .B lfs getstripe
  36 is used to list the layout/striping information for a given filename or
  37 directory tree.  By default the stripe_count, stripe_size, stripe_offset,
  38 and allocated OST objects for each file will be shown. If you only want
  39 specific layout information to be printed, then the
  40 .BR --stripe-count ,
  41 .BR --stripe-size ,
  42 .BR --extension-size ,
  43 .BR --stripe-index ,
  44 .BR --layout ,
  45 .BR --fid ,
  46 .BR --generation ,
  47 .BR --component-id ,
  48 .BR --component-flags ,
  49 .BR --component-count ,
  50 .BR --component-start ,
  51 .BR --component-end ,
  52 .BR --pool
  53 or
  54 .BR --mirror-index
  55 or
  56 .BR --mirror-id
  57 options, or equivalent single-character options, can be used without an
  58 argument to return only the specified field(s).
  59 .PP
  60 You can limit the displayed content to one or more specific components or
  61 mirror of a composite file layout by specifying the matching
  62 parameter(s) for the
  63 .BR --component-id ,
  64 .BR --component-flags ,
  65 .BR --component-start ,
  66 .BR --component-end ,
  67 .BR --mirror-index ,
  68 or
  69 .BR --mirror-id ,
  70 or their single-character options. For single-character options, the
  71 argument must follow the option without a space, and for long options an
  72 .RB ' = '
  73 sign must be used.
  74 .PP
  75 The default behavior when a directory is specified is to list the striping
  76 information for all files within the specified directory (like
  77 .RB ' "ls -l \fIDIRECTORY\fR" ').
  78 .SH OPTIONS
  79 .TP
  80 .BR --component-count | --comp-count
  81 Print only the number of components in the file's layout.
  82 .TP
  83 .BR --component-end | --comp-end | -E \fR[[ +- \fR] \fIEND_OFFSET\fR [ KMGTPE ]]
  84 Print only the component end offset (in bytes) for the component(s).
  85 If the component
  86 .I end
  87 offset is specified (with optional suffix for SI units), print only the
  88 attributes of the component(s) with the given end offset.  If
  89 .BI + END_OFFSET
  90 or
  91 .BI - END_OFFSET
  92 is used, print components with respectively a larger or smaller
  93 .I END_OFFSET
  94 offset.
  95 .TP
  96 .BR --component-flags \fR| --comp-flags \fR[ \fB^ \fR] \fICOMP_FLAG\fR ,...
  97 Print only the component flags.  If
  98 .I COMP_FLAG
  99 is specified, print only components matching the specified
 100 .I COMP_FLAG
 101 set.  If
 102 .BI ^ COMP_FLAG
 103 is used, print only components not matching
 104 .IR COMP_FLAG .
 105 Multiple flags may be specified, separated by commas.  Valid flag names are:
 106 .RS 1.2i
 107 .TP
 108 .B init
 109 Component has been initialized (has allocated OST objects).
 110 .TP
 111 .B stale
 112 Replicated (mirrored) components that do not have up-to-date data.  Stale
 113 components will not be used for read or write operations, and need to be
 114 resynched using
 115 .B lfs mirror resync
 116 before they can be accessed again.
 117 .TP
 118 .B prefer
 119 Replicated (mirrored) components that are preferred for read or write.
 120 For example, because they are located on SSD-based OSTs, or are more
 121 local on the network to clients.
 122 .TP
 123 .B prefrd
 124 Replicated (mirrored) components that are preferred for read.
 125 .TP
 126 .B prefwr
 127 Replicated (mirrored) components that are preferred for write.
 128 .TP
 129 .B nosync
 130 Replicated (mirrored) components that do not resync using \fB
 131 lfs mirror resync\fR.  Files with the \fBnosync\fR flag will also
 132 print the timestamp when the flag was set on the replica.
 133 .RE
 134 .TP
 135 .BR --component-id | --comp-id | -I \fR[ \fICOMP_ID\fR ]
 136 Print only the component COMP_ID number for the component(s).  The file-unique
 137 component COMP_ID is assigned as each component is created, and is not re-used.
 138 The COMP_ID is
 139 .B not
 140 necessarily related to the offset of the component within the file, in
 141 particular since replicated file layouts may have overlapping extents.
 142 If
 143 .I COMP_ID
 144 is specified, then print only the fields for the matching component.
 145 .TP
 146 .BR --component-start \fR| --comp-start \fR[ +- \fR] \fISTART_OFFSET\fR [ KMGTPE ]
 147 Print only the component start offset (in bytes) for the component(s).
 148 If the component
 149 .I START_OFFSET
 150 offset is specified (with optional suffix for SI units), print only the
 151 attributes of the component(s) with the given starting offset.  If
 152 .BI + START_OFFSET
 153 or
 154 .BI - START_OFFSET
 155 is used, print components with respectively a larger or smaller
 156 .I START_OFFSET
 157 offset.
 158 .TP
 159 .BR --directory | -d
 160 Get striping information for only the specified directory, like
 161 .RB ' "ls -d" '.
 162 .TP
 163 .BR --fid | -F
 164 Show only the 128-bit unique Lustre File Identifier (FID).
 165 .TP
 166 .BR --generation \fR| -g
 167 Print only the layout generation number.
 168 .TP
 169 .BR --help | -h
 170 Print usage message.
 171 .TP
 172 .BR --hex-idx
 173 Print OST and MDT indexes in hexademical rather than decimal.
 174 .TP
 175 .BR --layout
 176 Show only the file layout, which is one of:
 177 .RS 1.2i
 178 .TP
 179 .B raid0
 180 Traditional Lustre RAID-0 striping format.
 181 .TP
 182 .B released
 183 HSM-archived files that are not resident in the filesystem.
 184 .TP
 185 .B mdt
 186 Files that have the first data component on an MDT.
 187 .RE
 188 .TP
 189 .BR --mdt \fR| --mdt-index \fR| -m
 190 Show the MDT index on which the file or directory inode is located.
 191 .TP
 192 .BR --mirror-count \fR| -N
 193 Print the number of mirrors on the file.
 194 .TP
 195 .BR --mirror-index=\fR[\fB+-\fR]\fR\fIMIRROR_INDEX\fR
 196 Print only the components of \fIMIRROR_INDEX\fR-th mirror, based on the order
 197 that the mirror components are stored in the file layout. The \fIMIRROR_INDEX\fR
 198 starts at 1. If
 199 .BI + MIRROR_INDEX
 200 or
 201 .BI - MIRROR_INDEX
 202 is used, print components of mirror(s) respectively later or earlier than
 203 the \fIMIRROR_INDEX\fR-th mirror.
 204 .RS 1.2i
 205 .TP
 206 .B !
 207 Negates the meaning. Using + before \fIMIRROR_INDEX\fR means mirror appears 'later
 208 than \fIMIRROR_INDEX\fR',
 209 - before \fIMIRROR_INDEX\fR means mirror appears 'earlier
 210 than \fIMIRROR_INDEX\fR'. If
 211 neither is used, it means 'equal to \fIMIRROR_INDEX\fR'.
 212 .RE
 213 .TP
 214 .B --mirror-id=\fR[\fB+-\fR]\fR\fIMIRROR_ID\fR
 215 Print only the components of the mirror with ID of \fIMIRROR_ID\fR.
 216 The mirror IDs are assigned to new mirrors as they are created,
 217 but may not be sequential if some mirrors are removed. If
 218 .BI + MIRROR_ID
 219 or
 220 .BI - MIRROR_ID
 221 is used, print components of mirror(s) with respectively a larger or smaller
 222 mirror ID of
 223 .I MIRROR_ID
 224 .
 225 .RS 1.2i
 226 .TP
 227 .B !
 228 Negates the meaning. Using \fB+\fR before \fIMIRROR_ID\fR means mirror with ID
 229 'larger than \fIMIRROR_ID\fR', \fB-\fR before \fIMIRROR_ID\fR means mirror
 230 with ID 'smaller than \fIMIRROR_ID\fR'. If neither is used,
 231 it means 'equal to \fIMIRROR_ID\fR'.
 232 .RE
 233 .TP
 234 .BR --ost \fR| -O \fIOST_NAME\fR
 235 Print only file layouts and OST objects on the specified \fIOST_NAME\fR.
 236 .TP
 237 .BR --pool \fR| -p
 238 Print only the OST pool name on which the file was created.
 239 .TP
 240 .BR --quiet \fR| -q
 241 Print only allocated objects for each file, not other layout parameters.
 242 .TP
 243 .BR --raw \fR| -R
 244 Print layout information without substituting the filesystem's default values
 245 for unspecified fields. If the file layout is not set, 0, 0, and -1 will be
 246 printed for the stripe_count, stripe_size, and stripe_offset respectively.
 247 .TP
 248 .BR --recursive \fR| -r
 249 Recurse into all subdirectories.
 250 .TP
 251 .BR --stripe-count \fR| -c
 252 Print the number of stripes in the file.  For composite files this is
 253 the stripe count of the last initialized component.
 254 .TP
 255 .BR --stripe-index \fR| -i
 256 Print the starting OST index for the file layout.
 257 .TP
 258 .BR --stripe-size \fR| -S
 259 Print the stripe size in bytes.  For composite files this is the stripe
 260 size of the last initialized component.
 261 .TP
 262 .BR --extension-size \fR| --ext-size \fR| -z
 263 Print the extension size in bytes. For composite files this is the extension
 264 size of the first extension component.
 265 .TP
 266 .BR --verbose \fR| -v
 267 Also print the layout magic, FID sequence, FID object ID, and FID, in
 268 addition to the normally-printed attributes.
 269 .TP
 270 .BR --yaml \fR| -y
 271 Always print the layout in YAML format, rather than only using this
 272 format for composite files.
 273 .TP
 274 .BR --no-follow
 275 Print the stripe information of symbolic link itself.
 276 .br
 277 .SH EXAMPLES
 278 .TP
 279 .B $ lfs getstripe -v /mnt/lustre/file1
 280 List the detailed object allocation of the given file.
 281 .TP
 282 .B $ lfs getstripe -v -I2 /mnt/lustre/file1
 283 List the detailed information of only component with ID 2 of the given file.
 284 .TP
 285 .B $ lfs getstripe --mirror-index=+1 /mnt/lustre/file1
 286 Print the mirror(s) appearing later than the first mirror in the the file.
 287 .TP
 288 .B $ lfs getstripe ! --mirror-id=2 /mnt/lustre/file1
 289 Print the mirror(s) with mirror ID other than 2 in the file.
 290 .TP
 291 .B $ lfs getstripe --component-flags=^init -I /mnt/lustre/file1
 292 Print only the component IDs for all the uninitialized components.
 293 .TP
 294 .B $ lfs getstripe --component-flags=init,^stale -I /mnt/lustre/file1
 295 Print only the component(s) that are instantiated but not stale.
 296 .TP
 297 .B $ lfs getstripe -E-64M /mnt/lustre/file1
 298 List information of components in a file with extent end less than 64MiB.
 299 .TP
 300 .B $ lfs getstripe -I3 --component-start /mnt/lustre/file1
 301 Print only the component start for the component with ID of 3
 302 .TP
 303 .B $ lfs getstripe --yaml /mnt/lustre/file1
 304 Lists the information of the components of a file in YAML format.
 305 .SH AUTHOR
 306 The lfs command is part of the Lustre filesystem.
 307 .SH SEE ALSO
 308 .BR lfs (1),
 309 .BR lfs-find (1),
 310 .BR lfs-getdirstripe (1),
 311 .BR lfs-setstripe (1),
 312 .BR lustre (7)