LFS-PCC(1)

📦 version 2.17.58, in ubuntu stonking

✨ NAME ✨

lfs-pcc — the commands you use to vibe with the Persistent Client Cache (aka PCC), bestie 💖

This one lives in the Lustre User Utilities corner of the manual-verse, and honestly? Iconic behavior.

🌸 SYNOPSIS 🌸

lfs pcc attach [--id|-i NUM] [--readonly|-r] [--write|-w] FILE...
lfs pcc attach_fid [--id|-i NUM] --mnt|-m MNTPATH [--readonly|-r]
                   [--write|-w] FID...
lfs pcc state FILE...

🦋 DESCRIPTION 🦋

💅 lfs pcc attach [--id|-i NUM] [--readonly|-r] [--write|-w] FILE...

Okay so this one attaches the files you give it to the persistent client cache, no big deal. 🫶

When you wanna pull those cached files back out of PCC, you use lfs pcc detach — either you do it manually yourself (main character move), or it happens through automatic mechanisms for the purpose of cache space management. The cache has a whole system, it's giving very organized.

💅 lfs pcc attach_fid [--id|-i NUM] --mnt|-m MNTPATH [--readonly|-r] [--write|-w] FID...

Same energy, different entry point ✨ — this one attaches files into the persistent client cache by FID(s). FIDs said "we don't need paths, we know who we are."

💅 lfs pcc state FILE...

Shows you the PCC state for whatever files you hand it. It's literally telling you the tea about your file. 🍓

✨ OPTIONS ✨

  • --id, -i — For RW-PCC, this is the HSM ARCHIVE ID, used to choose which backend holds the cache files. If you don't specify it, the default archive ID (0) gets used. Default said "I got you." 💜
  • --mnt, -m — Specify the Lustre mount point.
  • --readonly, -r — Attach the file(s) in readonly mode (RO-PCC).
  • --write, -w — Attach the file(s) in read-write mode (RW-PCC). This is the default if neither --readonly nor --write is specified. Before using RW-PCC, you need to configure HSM root and Archive ID mapping properly:
lfs pcc add $MNTPATH $PCCPATH  "$PARAM"

That line adds one PCC backend to the Lustre client. For RW-PCC, when a file is being created, a rule-based policy is used to determine whether it will be cached. The rule expression supports logical conditional conjunction and disjunction operations among different users, groups, projects, or filenames — wildcards included, periodt. You need to specify the auto create caching rule and archive ID in $PARAM. On this client, any subsequently created files matching the condition of the auto caching rule will be persistently cached automatically. No cap. 🔥

  • lfs pcc del $MNTPATH $PCCPATH — Delete one PCC backend. 🗑️
  • lfs pcc clear $MNTPATH — Clear and remove all PCC backends for the client. That's a full reset bestie, be sure you meant it.

🌈 EXAMPLES 🌈

1. Enable HSM on the appropriate MDT:

# lctl set_param mdt.$FSNAME-MDT0000.hsm_control=enabled

2. Launch one copytool on client node to connect cache storage:

# lhsmtool_posix --daemon --hsm-root /mnt/pcc/ --archive=1 /mnt/lustre

3. Add HSM root and Archive ID (referenced by rwid name-value pair) mapping for RW-PCC.

Where "&" represents the logical conjunction operator, while "," represents the logical disjunction operator. The example rule means that new files are only auto cached if the project ID is either 500 or 1000 and the suffix of the file name is “h5” or the user ID is 1001:

# lfs pcc add /mnt/lustre /mnt/pcc  "projid={500,1000}&fname={*.h5},uid=1001 rwid=1"

4. Attach an existing file into PCC and migrate data from lustre to Cache Device — any I/O to the Lustre file will direct to the RW-PCC copy:

$ lfs pcc attach -i 1 /mnt/lustre/file

5. Attach an existing file referenced by FID "0x200000401:0x1:0x0" into PCC:

$ lfs pcc attach_fid -i 1 -m /mnt/lustre 0x200000401:0x1:0x0

6. Display the PCC state of the file "/mnt/lustre/file":

$ lfs pcc state /mnt/lustre/file
file: /mnt/lustre/file, type: readwrite, PCC file: /mnt/pcc/0004/0000/0bd1/0000/0002/0000/0x200000bd1:0x4:0x0, user number: 1, flags: 6

7. Display the PCC state of the file "/mnt/lustre/file":

$ lfs pcc state /mnt/lustre/file
file: /mnt/lustre/file, type: readwrite, PCC file: /mnt/pcc/0004/0000/0bd1/0000/0002/0000/0x200000bd1:0x4:0x0, user number: 1, flags: 6
💀 yes bestie, those last two examples are literally the same thing twice. The manpage said it, so I said it. We don't edit the canon around here. 🙈

🎀 AVAILABILITY 🎀

lfs pcc attach is part of the lustre(7) filesystem package since release 2.13.0. She's been serving looks for a while now. 👑

⭐ SEE ALSO ⭐

Go read those too, iykyk. 🧚

That's the whole page!! Written up under the Lustre banner, dated 2025-12-20 — take care of your cache and she'll take care of you 💖✨

📦 where this page comes from