MOUNT.LUSTRE(8)

📦 version 2.17.58, in ubuntu stonking

🌈 MOUNT.LUSTRE(8) — Lustre Configuration Utilities 🌈

🎀 NAME 🎀

mount.lustre, mount.lustre_tgt — mount helper for Lustre client/target service, periodt. 💖

✨ SYNOPSIS ✨

mount -t lustre [-o OPTIONS] MGSNAME:/FSNAME CLIENT_MOUNTPOINT
mount -t lustre_tgt [-o OPTIONS] BLOCK_DEVICE SERVER_MOUNTPOINT

💖 DESCRIPTION 💖

okay so mount.lustre and mount.lustre_tgt are the glow-up helpers that start a Lustre client or target service, respectively. They should not be called directly — they are helper programs invoked through mount(8) as above when the lustre or lustre_tgt filesystem type is used. And when you're done? Lustre clients and targets are stopped by using the umount(8) command. bye bestie 👋

There are two forms for the device option passed to the mount command, depending on whether a client or a target service is started:

  • MGSNAME:/FSNAME[/SUBDIR] — mounts the Lustre client filesystem named FSNAME (optionally starting at subdirectory SUBDIR within the filesystem, if specified) by contacting the Management Service at MGSNAME. slay.
  • CLIENT_MOUNTPOINT — is the directory where the client filesystem will be mounted and accessed. A client filesystem will typically be listed in fstab(5) for automatic mount at boot time, is usable like any local filesystem, and provides a full POSIX-compilant interface. yes, compilant, we keep the lore 💀
  • MGSNAME:=MGSNODE[:MGSNODE] — The MGSNAME may be a colon-separated list of MGSNODE servers where the MGS service may run. Multiple MGSNODE values can be specified if the MGS service is configured for High Availability and may be running on any one of the nodes. HA girlies understand.
  • MGSNODE:=MGSNID[,MGSNID] — Each MGSNODE may specify a comma-separated list of NIDs, if there are different LNet interfaces for the same MGSNODE. LNet interface buffet.
  • MGSNID:=HOST@NETTYPE[NET_NUMBER] — Each MGSNID contains a hostname that can be resolved via the hosts(5) name service in nsswitch.conf(5), or a numeric IP, IB, or other address that does not need resolution. The @NETTYPE is the LNet network type, such as @tcp, @o2ib or other supported LND type, @tcp0 if unspecified. The optional NET_NUMBER is the network number for that NETTYPE, or 0 if unspecified. network lore unlocked 🔓
  • BLOCK_DEVICE — specifies the physical disk or ZFS dataset uses to start the target service formatted by the mkfs.lustre(8) command. The BLOCK_DEVICE may be specified using -LLABEL to find the first block device with that label (e.g. testfs-MDT0000), or by UUID using the -UUUID option. Care should be taken if there is a device-level backup of the target filesystem, which would have a duplicate label and UUID if it is not changed with tune2fs(8) or similar. danger: duplicate label/UUID drama is real.
  • SERVER_MOUNTPOINT — is the directory where the target filesystem will be mounted, but is only useful for df(1) to show the current space usage, and ioctl(3) for block device operations such as resize2fs(8) or fstrim(8). It appears in /proc/mounts to show that BLOCK_DEVICE is in use. lowkey just there for the plot.

After successful mount, Lustre clients may have additional parameters set according to those listed in /etc/lustre/mount.client.params, and/or the /etc/lustre/mount.FSNAME.params files, with lines in the same style as command-line arguments to lctl-set_param(8), with the form PARAM=VALUE. parameter customization, periodt.

✨ OPTIONS ✨

Okay bestie, buckle up, this is the big one 🎀

  • mgssec=FLAVOR — sets the encryption flavour for that very first network RPC connection over to the MGS node. Here's the menu:
    • Non-security flavors are: null, plain, and gssnull, which respectively disable, or have no encryption or integrity features for testing purposes. (Yes, "testing purposes", don't @ me 🙈)
    • Kerberos flavors are: krb5n, krb5a, krb5i, and krb5p. 👑
    • Shared-secret key flavors are: skn, ska, ski, and skpi. 🗝️
    • See lgss_sk(8) for more details, fr fr. And heads up: the security flavour for client-to-server connections is specified in the filesystem configuration that the client fetches from the MGS. So this option is literally just the opening handshake vibe ✨
  • skpath=FILE|DIRECTORY — path to a file or a directory holding the keyfile(s) you wanna load for this mount command. 🌸 The keys get inserted into the KEY_SPEC_SESSION_KEYRING keyring with a description that contains "lustre:" plus a suffix which depends on whether the context of the mount command is for an MGS, MDT/OST, or client. If no skpath is specified for client mounts, the mount command will automatically check for a keyfile named .lgss in the mount point directory and load it if present (sneaky, iconic, thoughtful 💅). This option is only available when built with --enable-gss.
  • exclude=OSTLIST — start a client or MDT with a (colon-separated) list of known inactive OSTs. Basically "these ones are asleep, don't bother them" 😴

💅 CLIENT OPTIONS 💅

In addition to the standard options listed in mount(8), Lustre understands the following client-specific options:

  • flock — Enable full distributed flock(2) support, coherent across all client nodes also using this mount option. This is useful if applications need coherent userspace file locking across multiple client nodes, has no measurable performance impact in modern (2.x) versions of Lustre, is therefore the recommended mode, and is enabled by default in Lustre 2.12.3 and newer. The way that this is the default now... we love an upgrade that just fixes things 🫶
  • localflock — Enable local flock(2) support, using only client-local file locking. This is faster than mounting with the flock option, and can be used for applications that depend on functioning flock(2) but run only on a single node. Main character single-node energy 👑
  • noflock — Disables flock(2) support entirely. Applications calling flock(2) will get an ENOSYS error. It is possible to mount clients with different options, and only those mounted with flock will be coherent amongst each other. So yeah, mix-and-match is allowed, but only the flock girlies agree on anything 💀
  • lazystatfs — Allows statfs(2) (as used by df(1) and lfs-df(1)) to return even if some OST or MDT is unresponsive or has been temporarily or permanently disabled in the configuration. This avoids blocking until all of the targets are available. This is the default since Lustre 2.9.0. Lowkey the most chill option here ✨
  • nolazystatfs — Requires that statfs(2) block until all OSTs and MDTs are available and have returned space usage. No shortcuts, no vibes, we wait. 🧘
  • user_xattr — Enable get/set of extended attributes by regular users. See the attr(5) manual page.
  • nouser_xattr — Disable use of extended attributes by regular users. Root and system processes can still use extended attributes though, they always get the VIP pass 🎀
  • always_ping — Force a client to keep pinging even if servers have enabled suppress_pings. Like that friend who keeps texting even when you said you're busy. Persistent. Iconic. 📱
  • verbose — Enable mount/remount/umount console messages. Tell me everything 👀
  • noverbose — Disable mount/remount/umount console messages. Silence, bestie 🤫
  • user_fid2path — Enable FID to path translation by regular users via lfs fid2path.
  • nouser_fid2path — Disable FID to path translation by regular users. Root and process with CAP_DAC_READ_SEARCH can still perform FID to path translation. (Root stays winning, always 🔥)
  • network=NET — Limit connections from the client to be on the network NID specified by net. ´net´ designates a single network NID, like o2ib2 or tcp1. This option can be useful in case of several Lustre client mount points on the same node, with each mount point using a different network. It is also interesting when running Lustre clients from containers, by restricting each container to a specific network. Very "everyone stays in their own lane" of it 💅
Warning! network option is incompatible with LNet Dynamic Peer Discovery. If you want to restrict client NID, please make sure LNet Dynamic Peer Discovery is disabled. Like, actually make sure. No cap. ⚠️
  • mgsname=MGSNAME — Specify a custom hostname for the MGS that will be displayed in /proc/mounts instead of the resolved IP address. The network type (e.g., @tcp, @o2ib) is automatically extracted from the first MGS NID in the device string and should be included in the hostname. If this option is not specified and the device string contains a hostname (not an IP address), the hostname will be automatically extracted and used to generate the mgsname option. This option is purely cosmetic and does not affect the actual connection to the MGS, which is still determined by the device string. This can be useful for making mount entries more readable in system monitoring tools and if MGSNAME is specified as a hostname with DNS resolution that resolves to multiple NIDs instead of numeric addresses. So basically: it's the ✨aesthetic✨ option, purely for the look 🎀
  • test_dummy_encryption — Enable test dummy encryption mode. Testing only, she's a stunt double 💅
  • noencrypt — Disable Lustre client-side encryption. By default, Lustre client-side encryption is enabled, letting users define encryption policies on a per-directory basis. fscrypt userspace tool can be used for that purpose, see https://github.com/google/fscrypt 🔐
  • retry=NUM — Specify the number of times the mount attempt may be retried by the client, with an interval starting at 32 seconds for the first 5 minutes, and doubling for every two retries after that. It's giving ✨exponential backoff, but make it dramatic✨

🔥 SERVER OPTIONS 🔥

In addition to the standard mount options and backing disk type (e.g. ldiskfs) options listed in mount(8), Lustre understands the following server-specific options:

  • acl — Enable POSIX Access Control List support for all clients. See the acl(5) manual page. Sharing is caring 👑
  • no_create — Do not allow objects to be created on an OST, or new directories on an MDT after mounting. This allows a (potentially newly-formatted) MDT or OST to be started without clients starting to use it immediately. To allow the new target to be used for allocation, unmount and mount the target again without this option, or run lctl set_param obdfilter.FSNAME-OSTXXXX.no_create=0 or lctl set_param mdt.FSNAME-MDTXXXX.no_create=0 on the appropriate server node.
NOTE: this does not start the OST or MDT read-only, it only disables the creation of new objects there. This means existing objects can be read, modified, or deleted. If the OST or MDT is new then it will not have any objects on it yet. So like, door's locked for new stuff but everything inside is still fully accessible, okay? 🙈
  • nosvc — Only start the MGC (and MGS, if co-located) for a target service, and not the actual MDS or OSS service. Bare minimum mode 💅
  • noclient — Do not allow any client connections other than the local interface to the local MGS. This is helpful for the lctl replace_nids and clear_conf commands to prevent unwanted client connections. Do not disturb, we're working 🚧
  • nomgs — Start an MDT with a co-located MGS without starting the MGS service. Co-located but not that co-located 😌
  • noscrub — Do not trigger OI scrub automatically when an inconsistency is detected. It is still possible to start explicitly using the lctl lfsck_start. No auto-pilot, but manual mode still exists 🧚
  • skip_lfsck — Do not resume the former paused/crashed LFSCK automatically when mounting. We're not picking that back up right now, bestie 💀
  • abort_recov — Abort client recovery and start the target service immediately. No waiting, no patience, we move now 🔥
  • md_stripe_cache_size=cache_size — Sets the MD RAID stripe_cache_size parameter to cache_size KiB for server OST or MDT block device with a striped RAID configuration.
  • recovery_time_soft=timeout — Allow timeout seconds for clients to reconnect for recovery after a server crash. This timeout will be incrementally extended if it is about to expire and the server is still handling new connections from recoverable clients. The default soft recovery timeout is set to 300 seconds (5 minutes). Generous but not endless 🫶
  • recovery_time_hard=timeout — The server will be allowed to incrementally extend its timeout up to a hard maximum of timeout seconds. The default hard recovery timeout is set to 900 seconds (15 minutes). The absolute limit. No negotiations past this. Periodt. ✋

🛠️ COMMAND-LINE OPTIONS 🛠️

Some command-line options for mount.lustre itself may passed from the mount(8) command-line, but are mostly only available for debugging if the mount.lustre(8) command is run directly. These are separate from the mountpoint options passed to mount(2) for the mountpoint itself, which are listed in the OPTIONS section. (<- yes that's the section you just read, you're doing amazing sweetie 💖)

  • -f, --fake — Fake filesystem mount, setting client-specific parameters and adding it to /etc/fstab without actually calling the mount(2) system call. Together with the -v option this will show what mount options would be set for the filesystem. It's like a dress rehearsal, the mount version of "act natural" 🎭
  • --force — Force mounting the filesystem even if it appears to already be mounted. We're doing this anyway, bestie 💅
  • -h, --help — Print usage message and exit. Hello, I need assistance 👋
  • -n, --nomtab — Do not update the /etc/fstab file after the mount has successfully completed. Keep your fstab out of this 🙅
  • -o, --options — Specify the list of OPTIONS to pass to the kernel for MOUNTPOINT. These are normally passed from the mount command, but can be specified directly for debugging purposes.
  • -v, --verbose — Print extra information during mounting. This will be passed on from mount. Spill the tea ☕
  • -V, --version — Print the build version of the mount.lustre binary and exit. Identity check 🪪

🐛 BUGS 🐛

Not very many mount options can be changed with -o remount. That's the whole bug. She's short, she's honest, she's lowkey iconic for it 💀

💖 EXAMPLES 💖

Okay bestie, this is the part where we actually do stuff. Real commands, real vibes. Let's go 🌸

Start a client for the Lustre filesystem testfs at the mount point /mnt/myfilesystem. The Management Service is running on a node reachable via NID cfs21@tcp0:

client# mount -t lustre cfs21@tcp0:/testfs /mnt/myfilesystem

Same energy as the example above ⬆️ but the thing you're mounting is the subdirectory dir as a fileset:

client# mount -t lustre cfs21@tcp0:/testfs/dir /mnt/myfilesystem

Again, same as above ⬆️ except plot twist: the Management Service is running on one of the service nodes mgs1 and mgs2. These are two different hosts, separated by a colon, served as a failover pair, and they've got both TCP and IB addresses 🦋

Lustre tries the first one, and if that fails, it tries the second one. On each service node, those comma-separated NIDs refer to different interfaces on the same host, and the Lustre client picks whichever one is the best for communication based on which network interfaces are available locally. Choose-your-own-adventure but for NICs, no cap:

client# mount -t lustre mgs1@tcp0,mgs1ib@o2ib0:mgs2@tcp0,mgs2ib@o2ib0:/testfs /mnt/fs

Now we're the server side, main character energy 👑 Start the Lustre metadata target service from /dev/sda1 on mountpoint /mnt/test/mdt:

mds# mount -t lustre_tgt /dev/sda1 /mnt/test/mdt

Start the testfs-MDT0000 service (using the disk label, obviously 💅), but it aborts the Lustre client recovery process — which is exactly what you want when the clients are known to be unavailable:

mds# mount -t lustre_tgt -L testfs-MDT0000 -o abort_recov /mnt/test/mdt

Mount a client filesystem with a custom MGS name, purely for display purposes (it's giving ✨aesthetic✨). The network type @o2ib gets automatically appended to the MGS hostname cfs-mgs in /proc/mounts:

client# mount -t lustre -o mgsname=cfs-mgs@o2ib 10.0.0.2@o2ib,10.0.0.4@o2ib:/testfs /myfs

Last one, and it's the ✨effortless✨ one 🎀 Mount a client filesystem with automatic MGS name generation. The hostname test-mgs gets automatically extracted from the device string, and mgsname=test-mgs@tcp gets appended to the list of mount options so it shows up in /proc/mounts:

client# mount -t lustre test-mgs@o2ib:/testfs /mnt/myfs

🌈 AVAILABILITY 🌈

mount.lustre and mount.lustre_tgt are part of the lustre(7) filesystem package, bestie. mount.lustre was added in release 0.10.0, and mount.lustre_tgt was added in release 2.13.0. So if you're out here on some ancient version wondering where mount.lustre_tgt is… yeah, that's the reason 🙈

🦋 SEE ALSO 🦋

Go read these too, they're lowkey everything:

And that's the whole page, bestie!! 🥳 This beauty is from the Lustre gang, dated 2025-05-22, and it lives as MOUNT.LUSTRE(8). Go mount something iconic 💅💖✨

📦 where this page comes from