lfs-pool-pin(1)

NAME

lfs-pool-pin - pin files or files in directory to OST pool

SYNOPSIS

DESCRIPTION

The lfs pool pin command records that the specified FILE(s), or all files within the specified DIRECTORY(/ies), should maintain a mirror copy on the named OST POOL.

lfs pool pin inserts a pool entry for the selected POOL in the lustre.pin attribute, unless it is already present in which case the command succeeds without modifying the attribute.

When the --pool option is omitted, 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.

The --fid form of the command operates on files referenced by Lustre FIDs beneath the filesystem mounted at MOUNT, while the default and --file forms operate on filesystem paths.

Updating the 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 EPERM, typically due to the mdt.enable_pin_gid policy; see mdt.enable_pin_gid(4) for details.

OPTIONS

--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 fsname prefix (e.g. fsname.POOL), which is discarded before the pool name is used.

-f, --file

Interpret remaining arguments as filesystem paths (this is the default if neither --file nor --fid is given).

-F, --fid MOUNT

Interpret remaining arguments as Lustre FIDs within the filesystem mounted at MOUNT. This option is mutually exclusive with --file.

-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.

-h, --help

Display brief usage information for the lfs pool pin subcommand.

EXIT STATUS

The 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 lustre.pin. In particular, an exit status of EPERM indicates that the client was not permitted to modify lustre.pin; see mdt.enable_pin_gid(4) for the MDT-side policy controlling which users may pin or unpin files.

EXAMPLES

Pin a directory tree and a single file to the pool scratch:

$ lfs pool pin --pool scratch /mnt/testfs/proj /mnt/testfs/file

Pin a file to the pool inferred from its primary mirror layout:

$ lfs pool pin /mnt/testfs/file

Pin a file referenced by FID to the pool scratch:

$ lfs pool pin --pool scratch --fid /mnt/testfs 0x200000401:0x1:0x0

AVAILABILITY

The lfs pool pin command is part of the lustre(7) filesystem package since release 2.18.0.

SEE ALSO

lfs(1), lfs-pool(1), lfs-pool-pin_info(1), lfs-pool-unpin(1), llapi_pool_pin_file(3), mdt.enable_pin_gid(4), lustre(7)