lustre/doc/lfs-mirror-extend.1

   1 .TH LFS-MIRROR-EXTEND 1 2017-07-25 "Lustre" "Lustre Utilities"
   2 .SH NAME
   3 lfs-mirror-extend \- add mirror(s) to an existing file
   4 .SH SYNOPSIS
   5 .nh
   6 .ad l
   7 .B lfs mirror extend
   8 [\fB\-\-no\-verify\fR]
   9 \fB\-\-mirror\-count\fR|\fB\-N\fR[\fIMIRROR_COUNT\fR]
  10 [\fB\-\-bandwidth\-limit\fR|\fB\-W\fR \fIBANDWIDTH\fR]
  11 [\fB\-\-stats\fR|\fB\-\-stats\-interval\fR=\fISTATS_INTERVAL\fR]
  12 [\fISETSTRIPE_OPTIONS\fR|\fB\-f\fR \fIVICTIM_FILE\fR]
  13 \fIFILENAME\fR ...
  14 .SH DESCRIPTION
  15 This command adds mirror(s) to an existing file specified by the path name
  16 \fIFILENAME\fR.
  17 .br
  18 The file \fIFILENAME\fR can already be a mirrored file, or just a regular
  19 non-mirrored file. If it's a non-mirrored file, then the command will convert it
  20 to a mirrored file.
  21 .br
  22 The \fB\-\-mirror\-count\fR|\fB\-N\fR option is required and indicates how many
  23 mirrors that have the same layout will be added. It can be repeated multiple
  24 times to separate mirrors that have different layouts. The \fIMIRROR_COUNT\fR
  25 argument is optional and defaults to 1 if it's not specified; if specified, it
  26 must follow the option without a space.
  27 .br
  28 The \fISETSTRIPE_OPTIONS\fR specify the specific layout for the mirror. It can
  29 be a plain layout with specific striping pattern or a composite layout like
  30 Progressive File Layout (PFL) (see \fBlfs-setstripe\fR(1)).
  31 If \fISETSTRIPE_OPTIONS\fR are not specified,
  32 then the stripe options inherited from the previous component will be used.
  33 If \fIVICTIM_FILE\fR exists, then the
  34 command will merge the layout from that file as a mirror added to the
  35 mirrored file. After the command is finished, the victim file will be
  36 removed.  The \fISETSTRIPE_OPTIONS\fR cannot be specified with
  37 \fB\-f\fR \fIVICTIM_FILE\fR option in one command line.
  38 .br
  39 If \fIVICTIM_FILE\fR is specified, the utility will verify that the file contents
  40 from \fIVICTIM_FILE\fR are the same as \fIFILENAME\fR. Otherwise the command
  41 will return failure. However, option \fB\-\-no\-verify\fR can be used to
  42 override this verification. The option can save siginificant time on file
  43 comparison if the file size is large, but use it only when the file contents
  44 are known to be the same.
  45 .br
  46 If no option is specified, then the command will return an error.
  47 .SH OPTIONS
  48 .TP
  49 .BR \-\-mirror\-count\fR|\fB\-N\fR[\fIMIRROR_COUNT\fR]
  50 The number of mirrors that have the same layout to be added. The option can be
  51 repeated multiple times to separate mirrors that have different layouts. The
  52 \fIMIRROR_COUNT\fR argument is optional and defaults to 1 if it's not specified;
  53 if specified, it must follow the option without a space.
  54 .TP
  55 .I SETSTRIPE_OPTIONS
  56 The layout of one mirror. The options are the same as those for
  57 \fBlfs-setstripe\fR(1) command.
  58 If \fISETSTRIPE_OPTIONS\fR are not specified, then the stripe options inherited
  59 from the previous component will be used. This option cannot be specified with
  60 \fB\-f\fR \fIVICTIM_FILE\fR option.
  61 .TP
  62 .BR \-f\fR\ \fIVICTIM_FILE\fR
  63 The layout of \fIVICTIM_FILE\fR will be merged as a mirror added to the
  64 mirrored file. This option cannot be specified with \fISETSTRIPE_OPTIONS\fR
  65 option.
  66 .TP
  67 .BR \-\-no\-verify
  68 This option indicates not to verify the mirror(s) from victim file(s) in case
  69 the victim file(s) contains the same data as the original mirrored file.
  70 .TP
  71 .BR \-\-stats
  72 This option enables progress updates every 5 seconds, in YAML format.
  73 .TP
  74 .BR \-\-stats-interval=\fISTATS_INTERVAL
  75 This option enables progress updates every \fISTATS_INTERVAL\fR seconds, in YAML format.
  76 .TP
  77 .BR \-\-bandwidth\-limit\fR|\fB\-W\fR\fIBANDWIDTH\fR
  78 This option enables throttling so that mirror extending writes no more than
  79 \fIBANDWIDTH\fR bytes a second.  An optional suffix can be used to
  80 specify the units in
  81 .BR K ilobytes,
  82 .BR M egabytes
  83 or
  84 .BR  G igabytes.
  85 .SH EXAMPLES
  86 .TP
  87 .B lfs mirror extend -N2 /mnt/lustre/file1
  88 Add 2 mirrors to /mnt/lustre/file1. If file1 is a non-mirrored file, then the
  89 command will convert it to a mirrored file first and then add mirrors. Each
  90 mirror has the same default striping pattern with \fIstripe_count\fR and
  91 \fIstripe_size\fR inherited from filesystem-wide default values, and
  92 OST \fIpool_name\fR inherited from parent directory.
  93 .LP
  94 .B lfs mirror extend -N3 -E 1M -c 1 -E 32M -c 4 -S 16M -E eof -c -1
  95 .B /mnt/lustre/file1
  96 .in
  97 Add 3 PFL mirrors to /mnt/lustre/file1. Each mirror has the same specified PFL
  98 layout.
  99 .LP
 100 .B lfs mirror extend -N -c 1 -S 4M -N -c 2 -o 2,3 -p flash
 101 .B -N -p none /mnt/lustre/file1
 102 .in
 103 Add 3 plain layout mirrors to /mnt/lustre/file1. The first mirror has a single
 104 stripe and 4MB stripe size. The second mirror has two stripes and locates on
 105 OSTs with indices 2 and 3 allocated from the \fBflash\fR OST pool.
 106 It also has 4MB stripe size inherited from the first mirror.
 107 The third mirror has two stripes and 4MB stripe size inherited from the previous
 108 mirror, and also has inherited OST \fIpool_name\fR from parent directory.
 109 .LP
 110 .B lfs mirror extend -N2 -E 4M -c 2 --pool flash -E eof -c 4 -N3 -E 16M -c 4
 111 .B -S 16M --pool archive -E eof -c -1 /mnt/lustre/file1
 112 .in
 113 Add 5 PFL mirrors to /mnt/lustre/file1. The first and second mirrors have the
 114 same PFL layout. All of the components are allocated from the flash OST pool.
 115 The last three mirrors have the same PFL layout. All of these components have a
 116 stripe size of 16MB and use OSTs in the archive pool.
 117 .LP
 118 .B lfs mirror extend --no-verify -N -f /mnt/lustre/file2 -N -f /mnt/lustre/file3
 119 .B /mnt/lustre/file1
 120 .in
 121 Merge the layouts from /mnt/lustre/file2 and /mnt/lustre/file3, which contain
 122 the same data as /mnt/lustre/file1, use the layouts as mirrors and add them to
 123 /mnt/lustre/file1 without verification.
 124 .SH AUTHOR
 125 The \fBlfs mirror extend\fR command is part of the Lustre filesystem.
 126 .SH SEE ALSO
 127 .BR lfs (1),
 128 .BR lfs-setstripe (1),
 129 .BR lfs-mirror-create (1),
 130 .BR lfs-mirror-delete (1),
 131 .BR lfs-mirror-split (1),
 132 .BR lfs-mirror-resync (1),
 133 .BR lfs-mirror-verify (1)