.TH LFS-POOL-PIN 1 2026-09-14 "Lustre" "Lustre User Utilities"
.SH NAME
lfs-pool-pin \- pin files or files in directory to OST pool
.SH SYNOPSIS
.SY "lfs pool pin"
.RB [ --pool
.IR POOL ]
.RB [ --quiet ]
.RB [ --file ]
.IR FILE " | " DIRECTORY " ..."
.SY "lfs pool pin"
.RB [ --pool
.IR POOL ]
.RB [ --quiet ]
.B --fid
.IR MOUNT
.IR FID " ..."
.YS
.SH DESCRIPTION
The
.B lfs pool pin
command records that the specified
.IR FILE (s),
or all files within the specified
.IR DIRECTORY (/ies),
should maintain a mirror copy on the named OST
.IR POOL .
.PP
.B lfs pool pin
inserts a
.B pool
entry for the selected
.IR POOL
in the
.B lustre.pin
attribute, unless it is already present in which case the command succeeds
without modifying the attribute.
.PP
When the
.B --pool
option is omitted,
.IR POOL
is inferred from the primary mirror layout of each file or directory.  If the
layout does not have an associated pool, the operation fails for that target
and an error message is printed.
.PP
The
.B --fid
form of the command operates on files referenced by Lustre FIDs beneath the
filesystem mounted at
.IR MOUNT ,
while the default and
.B --file
forms operate on filesystem paths.
.PP
Updating the
.B lustre.pin
attribute requires both appropriate write permissions on the target and
sufficient privileges on the MDT.  If these checks fail the operation will
return
.BR EPERM ,
typically due to the
.B mdt.enable_pin_gid
policy; see
.BR mdt.enable_pin_gid (4)
for details.
.SH OPTIONS
.TP
.BR --pool " " POOL
Name of the OST pool to which the specified files should be pinned.  The name
must consist of only alphanumeric characters, underscores and hyphens, and
may optionally be qualified with an
.IR fsname
prefix (e.g.
.IR fsname . POOL ),
which is discarded before the pool name is used.
.TP
.BR -f ", " --file
Interpret remaining arguments as filesystem paths (this is the default if
neither
.B --file
nor
.B --fid
is given).
.TP
.BR -F ", " --fid " " MOUNT
Interpret remaining arguments as Lustre FIDs within the filesystem mounted at
.IR MOUNT .
This option is mutually exclusive with
.BR --file .
.TP
.BR -q ", " --quiet
Suppress per-target error messages (such as a target that cannot be opened or
an unrecognized FID); the exit status still reflects any errors encountered.
.TP
.BR -h ", " --help
Display brief usage information for the
.B lfs pool pin
subcommand.
.SH EXIT STATUS
The
.B lfs pool pin
command returns 0 on complete success.  A non-zero exit status is returned if
any argument is invalid, a pool cannot be inferred when required, or an error
occurs while updating
.BR lustre.pin .
In particular, an exit status of
.B EPERM
indicates that the client was not permitted to modify
.BR lustre.pin ;
see
.BR mdt.enable_pin_gid (4)
for the MDT-side policy controlling which users may pin or unpin files.
.SH EXAMPLES
Pin a directory tree and a single file to the pool scratch:
.EX
.B $ lfs pool pin --pool scratch /mnt/testfs/proj /mnt/testfs/file
.EE
.PP
Pin a file to the pool inferred from its primary mirror layout:
.EX
.B $ lfs pool pin /mnt/testfs/file
.EE
.PP
Pin a file referenced by FID to the pool scratch:
.EX
.B $ lfs pool pin --pool scratch --fid /mnt/testfs 0x200000401:0x1:0x0
.EE
.SH AVAILABILITY
The
.B lfs pool pin
command is part of the
.BR lustre (7)
filesystem package since release 2.18.0.
.SH SEE ALSO
.BR lfs (1),
.BR lfs-pool (1),
.BR lfs-pool-pin_info (1),
.BR lfs-pool-unpin (1),
.BR llapi_pool_pin_file (3),
.BR mdt.enable_pin_gid (4),
.BR lustre (7)