.TH LFS-CHANGELOG 1 2025-11-25 Lustre "Lustre User Utilities"
.SH NAME
lfs-changelog, lfs-changelog_clear \- client utility to read and clear Lustre changelogs
.SH SYNOPSIS
.SY "lfs changelog"
.RB [ \-\-follow ]
.RB [ \-\-user
.IR USERNAME ]
.RB [ \-\-mask
.IR MASK ]
.I MDTNAME
.RI [ STARTREC
.RI [ ENDREC ]]
.SY "lfs changelog_clear"
.I MDTNAME
.I ID
.I ENDREC
.YS
.SH DESCRIPTION
.B lfs changelog
displays the metadata changes on an MDT.
Start point
.I STARTREC
and end point
.I ENDREC
are optional.
.PP
.B lfs changelog_clear
indicates that changelog records previous to
.I ENDREC
are no longer of interest to a particular consumer
.IR ID ,
potentially allowing the MDT to free up disk space.
An
.I ENDREC
of 0 indicates the current last record.
.PP
Changelog consumers must be registered on the MDT node using
.BR lctl-changelog_register (8).
.SH OPTIONS
.TP
.B \-\-follow
Block and wait for new changelog records to arrive.
.TP
.BI \-\-user\  USERNAME
Specify a registered changelog username for filtering.
The format of
.I USERNAME
can be a username or numeric ID, e.g., "cl1", "cl1-user", "1", or "user".
.TP
.BI \-\-mask\  MASK
Specify a changelog event filtering mask in the same format as
.BR lctl-changelog_register (8),
e.g., "creat,unlnk,+open,-hsm".
If
.I MASK
is not specified, the user's
.I MASK
specified to
.BR lctl-changelog_register (8)
will be used.
.SH RETURN VALUES
Return 0 on success or a errno value on failure.
.SH ERRORS
.TP 15
.B EINVAL
One or more invalid arguments are given.
.TP
.B ENOENT
MDT's changelog char device or changelog user not found.
.TP
.B EACCES
Not enough permissions to open the changelog char device. By default, the device
is only accessible to the root user.
.TP
.B EIO
Failed to read the changelog record on the MDT.
.SH NOTES
Certain userspace tools might rely on past Lustre behavior of displaying the
shard's parent FID instead of the real parent FID, in changelog records related
to striped directories or filesystem objects contained within them; if this
behavior is needed for compatibility, please set mdd.*.enable_shard_pfid=1. This
tunable might be deprecated in a future Lustre release.
.SH EXAMPLES
Register 2 changelog consumers on MDT0000:
.RS
.EX
.RB "mds# " "lctl changelog_register --device lfs1-MDT0000"
lfs1-MDT0000: Registered changelog userid 'cl1'
.RB "mds# " "lctl changelog_register --device lfs1-MDT0000 -u dirs -m mkdir+rmdir"
lfs1-MDT0000: Registered changelog userid 'cl2-dirs'
.EE
.RE
.PP
Set changelog mask to generate changelogs for file creations:
.RS
.EX
.RB "mds# " "lctl set_param mdd.lfs1-MDT0000.changelog_mask=CREAT"
mdd.lfs1-MDT0000.changelog_mask=CREAT
.EE
.RE
Generate changelogs by creating some files on the fs:
.RS
.EX
.B client# touch /mnt/lfs1/test{1..101}
.EE
.RE
Read changelog from number 0 to 99 on MDT0000:
.RS
.EX
.RB "client# " "lfs changelog lfs1-MDT0000 0 99"
0 01CREAT 11:03:54.129724442 2022.11.22 ... p=[0x200000007:0x1:0x0] test1
 ....
99 01CREAT 11:03:54.129724465 2022.11.22 ... p=[0x200000007:0x1:0x0] test100
.EE
.RE
.PP
Read changelog records using registered user cl1:
.RS
.EX
.RB "client# " "lfs changelog --user cl1 lfs1-MDT0000"
100 01CREAT 11:03:54.129724492 2022.11.22 ... p=[0x200000007:0x1:0x0] test101
.EE
.RE
.PP
Read changelog records for registered user cl2-dirs with an extra filter mask:
.RS
.EX
.RB "client# " "lfs changelog --user cl2-dirs --mask unlnk lfs1-MDT0000"
No record found.
.RE
.EE
.PP
Inform MDT0000 that changelogs lower than 100 are not needed for user
.BR cl1 :
.RS
.EX
.RB "client# " "lfs changelog_clear lfs1-MDT0000 cl1 99"
.EE
.RE
.PP
Inform MDT0000 that changelogs lower than 200 are not needed for user
.BR cl2-dirs :
.RS
.EX
.RB "client# " "lfs changelog_clear lfs1-MDT0000 cl2-dirs 199"
.RE
.EE
.PP
The changelogs from 0 to 99 are cleared by the MDT:
.RS
.EX
.RB "client# " "lfs changelog lfs1-MDT0000 0"
100 01CREAT 11:03:54.129724492 2022.11.22 ... p=[0x200000007:0x1:0x0] test101
.EE
.RE
.SH AVAILABILITY
.B lfs changelog
and
.B lfs changelog_clear
are part of the
.BR lustre (7)
filesystem package since release 2.0.0.
\" Added in commit 1.6.0-2259-g0e660eab78
.SH SEE ALSO
.BR lfs (1),
.BR llapi_changelog_clear (3),
.BR llapi_changelog_recv (3),
.BR llapi_changelog_start (3),
.BR llapi_changelog_start_user (3),
.BR lctl-changelog_deregister (8),
.BR lctl-changelog_register (8)