TUNEFS.LUSTRE(8)

📦 version 2.17.58, in ubuntu stonking

✨ tunefs.lustre — modify the Lustre configuration information on a disk ✨

okay bestie, welcome to tunefs.lustre(8), which lives in the Lustre Configuration Utilities part of the manual fam. sit down, grab a lil snack, we're gonna glow up a Lustre target disk together 💅

🌸 NAME 🌸

tunefs.lustre — modify the Lustre configuration information on a disk

🎀 SYNOPSIS 🎀

tunefs.lustre [OPTIONS] DEVICE

🦋 DESCRIPTION 🦋

So like. tunefs.lustre is the girl who goes in and messes with the configuration information on a Lustre target disk. That includes upgrading old disks (we're talking pre-Lustre 1.6 era, ancient lore fr).

It does not reformat the disk, and it does not erase the target information. BUT — and listen closely bestie — modifying the configuration information can result in an unusable filesystem. You have been warned. 😭

Also! Changes made here affect a filesystem only when the target is next mounted. So it's giving "queued up, drops on next mount" energy, not instant.

💖 OPTIONS 💖

  • --comment=COMMENT — drop a lil user comment about this disk. Lustre literally ignores it, it's just for you 🫶
  • --dryrun — only prints what would be done. Doesn't touch the disk at all. It's the "adding to cart" of tunefs✨
  • --erase-param PARAM — removes all previously stored instances of the parameter param. And the gag is: if you try to remove a parameter that doesn't even exist, it still acts like it worked (successful vibes only 💅)
  • --erase-params — nukes all previously stored parameter info. bye girl 👋
  • --failnode=NID,... — sets the NID(s) of a failover partner. You can repeat this option as many times as you want. Cannot be used with --servicenode.
  • --servicenode=NID,.... — sets the NID(s) of all service partner. This one treats all nodes as equal service nodes. Cannot be used with --failnode.
  • --fsname=FILESYSTEM_NAME — the Lustre filesystem this service will be part of. Default is 'lustre'.
  • --index=INDEX — force a particular OST or MDT index. main character gets to pick her own number 😌
  • --mountfsoptions=OPTS — sets the persistent mount options that will be used when Lustre fs. ⚠️ WARNING: unlike earlier versions of tunefs.lustre, this version completely replaces the existing mount options with those specified on the command line — and it throws a warning on stderr if any of the default mount options are omitted. The defaults for ldiskfs are:
OST :  errors=remount-ro,mballoc,extents
MGS/MDT:
       errors=remount-ro,user_xattr
DO NOT alter the default mount options unless you know what you are doing. fr fr, no cap.
  • --backfs-mount-opts=OPTS — use these options for mounting backing fs while tunefs.lustre is working.
  • --network=NET,... — network(s) to restrict this ost/mdt to. This option can be repeated as desired.
  • --mgs — add a configuration management service to this target. she's official now 👑
  • --mgsnode=NID,... — set the NID(s) of the MGS node. This is required for all targets other than the MGS.
  • --nomgs — remove a configuration management service to this target. no more MGS era 🚫
  • --skipmmp — disables the Multi-Mount Protection (MMP) feature even when failover nodes are configured. By default, MMP is automatically enabled when failover is configured. Use this option only if you have alternative mount protection mechanisms in place. This will remove the MMP feature from the filesystem if it was previously enabled.
⚠️ WARNING: Disabling MMP without alternative protection may lead to filesystem corruption. like, actual corruption. be so careful bestie 💀
  • --param KEY=VALUE — set permanent parameter KEY to value VALUE. This option can be repeated as desired. All previously stored instances of KEY are removed, and new instances specified in the command line are added. Typical options might include:
    • --param sys.timeout=40 — System obd timeout
    • --param lov.stripesize=2M — Default stripe size
    • --param lov.stripecount=2 — Default stripe count
    • --param failover.mode=failout — Return errors instead of waiting for recovery
  • --force-nohostid — ignore unset hostid for ZFS import protection. To set hostid, either set the spl_hostid option for spl.ko or set /etc/hostid, see zgenhostid(8).
  • --mountdata-reset-from=DEV|FILE — reset the CONFIGS/mountdata file using the path to a similar local device or a backup CONFIG/mountdata file.
  • --quiet — print less information. shhh 🤫
  • --verbose — print more information. tell me everything 🗣️
  • --writeconf — erase the configuration logs for the filesystem that this server is part of, and regenerate them.
🔥 This is very dangerous. All clients must be unmounted and servers for this filesystem should be stopped. All targets (OSTs/MDTs) must then be restarted to regenerate the logs. No clients should be started until all targets have restarted.

Correct order of operations is:

  • Unmount all clients of this filesystem.
  • Unmount MDT and all OSTs of this filesystem.
  • Run tunefs.lustre --writeconf <device> on every server.
  • Mount MDT and OSTs.
  • Mount clients
  • --nolocallogs — use configuration logs from the MGS, not local ones.

There is feature that starts a target with a local copy of the config log in order to avoid a delay in communicating with the MGS and to load MGS log updates later on. However, that feature is not always useful.

replace_nids changes config logs on the server side and local copies become invalid. --nolocallogs sets the nolocallogs mount flag, which causes the local copy of the config log to be ignored. The flag is reset once new logs are downloaded from MGS.

  • --quota — enable space accounting on old 2.x devices.
  • --replace — reset the state of a target that is already registered with the MGS and is returning an error (EADDRINUSE=98) that its index is already used, like:
# mount -t lustre /dev/vg_testfs_ost1/lvost1
mount.lustre: mount failed: Address already in use

This might happen if a new target is re-using the index of a previous target that was permanently removed or reformatted for some reason (e.g. hardware replacement, multiple disk failure), and mkfs.lustre was used to reformat the target without the --repace option. This can also happen if there was an error during initial target registration with the MGS (e.g. a network error or MGS failure on first mount). This stops the target trying to register with the MGS as a newly-added target with the filesystem.

📝 NOTE: this is a potentially dangerous operation that overrides internal safety checks in the filesystem. If it used incorrectly it may lead to filesystem corruption or data loss, so it should be used with caution after verifying that there are not two different devices using the same index number (e.g. by checking on all servers with blkid(8) to that the filesystem UUIDs and volume names are unique).

🌈 EXAMPLES 🌈

Change the MGS NID address. (This should be done on every target disk, since they should all be contacting the same MGS.):

# tunefs.lustre --erase-params --mgsnode=NEW_NID --writeconf /dev/sda

Remove all previous failover NID locations for this target, and add a new failover NID location for this target:

# tunefs.lustre --param failover.node=192.168.0.13@tcp0 /dev/sda

Remove all failover NID locations for this target:

# tunefs.lustre --erase-param failover.node /dev/sda

Force the targets to re-register with the MGS on their next mount to recreate the filesystem configuration logs in case of an error. This should be run for every target disk in the filesystem:

# tunefs.lustre --writeconf /dev/vgtestfs/lvtestfs-mdt0
# tunefs.lustre --writeconf /dev/vgtestfs/lvtestfs-ost0

⭐ AVAILABILITY ⭐

tunefs.lustre is part of the lustre(7) filesystem package since release 1.4.0. she's been iconic for a minute 💜

👑 SEE ALSO 👑

lfs(1), lustre(7), blkid(8), lctl(8), mkfs.lustre(8), mount.lustre(8)

and that's the whole page bestie 🫶 this one shipped from Lustre on 2024-08-28 — go forth, tune those filesystems, and pls pls pls read the warnings before you --writeconf anything 😭💖✨

📦 where this page comes from