.TH LUSTRE_RSYNC 8 2024-08-28 Lustre "Lustre Configuration Utilities"
.SH NAME
lustre_rsync \- Utility to replicate a Lustre Filesystem
.SH SYNOPSIS
.SY lustre_rsync
.RB { --source | -s
.IR SRC }
.RB { --target | -t
.IR TGT }
.RB { --mdt | -m
.IR MDT }
.RB [ --user | -u
.IR USER ID ]
.RB [ --xattr | -x " {" yes | no }]
.RB [ --verbose | -v ]
.RB [ --statuslog | -l
.IR LOG ]
.RB [ --dry-run ]
.RB [ --abort-on-err ]
.SY lustre_rsync
.RB { --statuslog | -l
.IR LOG }
.SY lustre_rsync
.RB { --statuslog | -l
.IR LOG }
.RB { --source | -s
.IR SOURCE }
.RB { --target | -t
.IR TGT }
.RB { --mdt | -m
.IR MDT }
.YS
.SH DESCRIPTION
.B lustre_rsync
is designed to replicate a Lustre filesystem (source filesystem) to
another target filesystem (any filesystem type) efficiently by 
using Lustre MDT changelogs.  A changelog user must be registered
(see lctl (8) changelog_register) before using this tool.
.PP
The source and the target filesystems must be identical before
the changelog user is registered. If the filesystems are discrepant,
a utility like rsync may be used to make them identical.
.SH OPTIONS
.TP
.BR -s ", " --source= \fISRC
The path to the root of the Lustre filesystem which will be replicated.
Mandatory if a valid statuslog created during an previous replication operation
(--statuslog) is not specified.
.TP
.BR -t ", " --target= \fITGT
The path to the root where the filesystem we be replicated. Mandatory
if a valid statuslog created during an previous replication operation
(--statuslog) is not specified. This option can be repeated if
multiple replication targets are desired.
.TP
.BR -m ", " --mdt= \fIMDT
The metadata device which is to be replicated. A changelog user must be
registered for this device. Mandatory if a valid statuslog created
during an previous replication operation (--statuslog) is not
specified.
.TP
.BR -u ", " --user= \fIUSER_ID
The changelog user id for the above MDT device. See lctl(8) changelog_register.
Mandatory if a valid statuslog created during an previous replication operation
(--statuslog) is not specified.
.TP
.BR -l ", " --statuslog= \fILOG
A status log file to which the status of replication is saved.
When lustre_rsync is started, the state from a previous replication
will be read from here.
.IP
If a statuslog from a previous replication operation is specified, the
otherwise mandatory options like --source, --target and --mdt may be
skipped.
.IP
By specifying the options like --source, --target and --mdt in
addition to the --statuslog option, the parameters in the statuslog
can be overridden. The command line options take precedence over the
ones from the statuslog.
.TP
.BR -x ", " --xattr " {" yes | no }
Specify whether extended attributes are replicated or not. The default
is to replicate extended attributes. Disabling xattrs will mean that
Lustre striping information will not be replicated.
.TP
.BR -v ", " --verbose
Produce a verbose output.
.TP
.B --dry-run
Shows what the program would do without actually replicating data.
.TP
.B --abort-on-err
Stop processing upon first error.  Default is to continue processing.
.SH EXAMPLES
Register a changelog consumer for MDT lustre-MDT0000:
.RS
.EX
.B # ssh $MDS lctl changelog_register --device lustre-MDT0000 -n
cl1
.EE
.RE
.PP
Replicate the lustre filesystem /mnt/lustre to /mnt/target:
.RS
.EX
.B # lustre_rsync --source=/mnt/lustre --target=/mnt/target \
--mdt=lustre-MDT0000 --user=cl1 --statuslog replicate.log  --verbose
Lustre filesystem: lustre
MDT device: lustre-MDT0000
Source: /mnt/lustre
Target: /mnt/target
Statuslog: replicate.log
Changelog registration: cl1
Starting changelog record: 0
Errors: 0
lustre_rsync took 1 seconds
Changelog records consumed: 22
.EE
.RE
.PP
After the filesystem undergoes some changes, replicate the changes.
Only the statuslog needs to be specified as it has all the
parameters passed earlier:
.RS
.EX
.B # lustre_rsync --statuslog replicate.log --verbose
Replicating Lustre filesystem: lustre
MDT device: lustre-MDT0000
Source: /mnt/lustre
Target: /mnt/target
Statuslog: replicate.log
Changelog registration: cl1
Starting changelog record: 22
Errors: 0
lustre_rsync took 2 seconds
Changelog records consumed: 42
.EE
.RE
.PP
To replicate the lustre filesystem /mnt/lustre to /mnt/target1 and /mnt/target2:
.RS
.EX
.B # lustre_rsync --source=/mnt/lustre --target=/mnt/target1 \
--target=/mnt/target2 --mdt=lustre-MDT0000 --user=cl1 --statuslog replicate.log
.EE
.RE
.SH AVAILABILITY
The
.B lustre_rsync
command is part of the
.BR lustre (7)
filesystem package since release 1.7.0
.\" Added in commit 1.6.1-3324-gb53302d92d
.SH SEE ALSO
.BR lfs (1),
.BR lustre (7),
.BR lctl (8)