lfs-changelog(1)

NAME

lfs-changelog, lfs-changelog_clear - client utility to read and clear Lustre changelogs

SYNOPSIS

DESCRIPTION

lfs changelog displays the metadata changes on an MDT. Start point STARTREC and end point ENDREC are optional.

lfs changelog_clear indicates that changelog records previous to ENDREC are no longer of interest to a particular consumer ID, potentially allowing the MDT to free up disk space. An ENDREC of 0 indicates the current last record.

Changelog consumers must be registered on the MDT node using lctl-changelog_register(8).

OPTIONS

--follow

Block and wait for new changelog records to arrive.

--user USERNAME

Specify a registered changelog username for filtering. The format of USERNAME can be a username or numeric ID, e.g., "cl1", "cl1-user", "1", or "user".

--mask MASK

Specify a changelog event filtering mask in the same format as lctl-changelog_register(8), e.g., "creat,unlnk,+open,-hsm". If MASK is not specified, the user's MASK specified to lctl-changelog_register(8) will be used.

RETURN VALUES

Return 0 on success or a errno value on failure.

ERRORS

EINVAL

One or more invalid arguments are given.

ENOENT

MDT's changelog char device or changelog user not found.

EACCES

Not enough permissions to open the changelog char device. By default, the device is only accessible to the root user.

EIO

Failed to read the changelog record on the MDT.

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.

EXAMPLES

Register 2 changelog consumers on MDT0000:

mds# lctl --device lfs1-MDT0000 changelog_register
lfs1-MDT0000: Registered changelog userid 'cl1'
mds# lctl --device lfs1-MDT0000 changelog_register -u dirs -m mkdir+rmdir
lfs1-MDT0000: Registered changelog userid 'cl2-dirs'

Set changelog mask to generate changelogs for file creations:

mds# lctl set_param mdd.lfs1-MDT0000.changelog_mask=CREAT
mdd.lfs1-MDT0000.changelog_mask=CREAT

Generate changelogs by creating some files on the fs:

client# touch /mnt/lfs1/test{1..101}

Read changelog from number 0 to 99 on MDT0000:

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

Read changelog records using registered user cl1:

client# lfs changelog --user cl1 lfs1-MDT0000
100 01CREAT 11:03:54.129724492 2022.11.22 ... p=[0x200000007:0x1:0x0] test101

Read changelog records for registered user cl2-dirs with an extra filter mask:

client# lfs changelog --user cl2-dirs --mask unlnk lfs1-MDT0000
No record found.

Inform MDT0000 that changelogs lower than 100 are not needed for user
cl1:

client# lfs changelog_clear lfs1-MDT0000 cl1 99

Inform MDT0000 that changelogs lower than 200 are not needed for user
cl2-dirs:

client# lfs changelog_clear lfs1-MDT0000 cl2-dirs 199

The changelogs from 0 to 99 are cleared by the MDT:

client# lfs changelog lfs1-MDT0000 0
100 01CREAT 11:03:54.129724492 2022.11.22 ... p=[0x200000007:0x1:0x0] test101

AVAILABILITY

lfs changelog and lfs changelog_clear are part of the lustre(7) filesystem package since release 2.0.0.

SEE ALSO

lfs(1), llapi_changelog_clear(3), llapi_changelog_recv(3), llapi_changelog_start(3), llapi_changelog_start_user(3), lctl-changelog_deregister(8), lctl-changelog_register(8)