LFS-POOL-PIN(1) Lustre User Utilities LFS-POOL-PIN(1)

# [NAME](#NAME)

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

# [SYNOPSIS](#SYNOPSIS)

`lfs pool pin` \[**--pool** *POOL*] \[**--quiet**] \[**--file**] *FILE* | *DIRECTORY* ...

`lfs pool pin` \[**--pool** *POOL*] \[**--quiet**] **--fid** *MOUNT* *FID* ...

# [DESCRIPTION](#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)](/man/enterprise-packages/lustre/mdt.enable_pin_gid.4) for details.

# [OPTIONS](#OPTIONS)

[**--pool** **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**](#f)

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

[**-F**, **--fid** **MOUNT**](#F)

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

[**-q**, **--quiet**](#q)

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**](#h)

Display brief usage information for the **lfs pool pin** subcommand.

# [EXIT STATUS](#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)](/man/enterprise-packages/lustre/mdt.enable_pin_gid.4) for the MDT-side policy controlling which users may pin or unpin files.

# [EXAMPLES](#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](#AVAILABILITY)

The **lfs pool pin** command is part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) filesystem package since release 2.18.0.

# [SEE ALSO](#SEE_ALSO)

[**lfs**(1)](/man/enterprise-packages/lustre/lfs.1), [**lfs-pool**(1)](/man/enterprise-packages/lustre/lfs-pool.1), [**lfs-pool-pin\_info**(1)](/man/enterprise-packages/lustre/lfs-pool-pin_info.1), [**lfs-pool-unpin**(1)](/man/enterprise-packages/lustre/lfs-pool-unpin.1), [**llapi\_pool\_pin\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_pin_file.3), [**mdt.enable\_pin\_gid**(4)](/man/enterprise-packages/lustre/mdt.enable_pin_gid.4), [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7)

2026-09-14 Lustre

---

Document: lfs-pool-pin(1) from lustre 2.17.60-r0 (Chainguard OS)
Source: https://github.com/lustre/lustre-release