.\" -*- nroff -*-
.\" Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
.\"
.\" Copyright (c) 2012, 2017, Intel Corporation.
.\"
.\" This file may be copied under the terms of the GNU Public License v2.
.\"
.TH MOUNT.LUSTRE 8 2025-05-22 Lustre "Lustre Configuration Utilities"
.SH NAME
mount.lustre, mount.lustre_tgt \- mount helper for Lustre client/target service
.SH SYNOPSIS
.SY "mount -t lustre"
.BR [ -o
.IR OPTIONS ]
.IR MGSNAME :/ FSNAME
.I CLIENT_MOUNTPOINT
.SY "mount -t lustre_tgt"
.BR [ -o
.IR OPTIONS ]
.I BLOCK_DEVICE
.I SERVER_MOUNTPOINT
.YS
.SH DESCRIPTION
.B mount.lustre
and
.B mount.lustre_tgt
are used to start a Lustre client or target service, respectively. They
should not be called directly; rather they are helper programs invoked through
.BR mount (8)
as above when the
.B lustre
or
.B lustre_tgt
filesystem type is used. Lustre clients and targets are stopped by using the
.BR umount (8)
command.
.P
There are two forms for the device option passed to the
.I mount
command, depending on whether a client or a target service is started:
.TP
.IB MGSNAME :/ FSNAME\fR[ / SUBDIR \fR]
mounts the Lustre client filesystem named
.I FSNAME
(optionally starting at subdirectory
.I SUBDIR
within the filesystem, if specified)
by contacting the Management Service at
.IR MGSNAME .
.TP
.I CLIENT_MOUNTPOINT
is the directory where the client filesystem will be mounted and accessed.
A client filesystem will typically be listed in
.BR fstab (5)
for automatic mount at boot time, is usable like any local filesystem, and
provides a full POSIX-compilant interface.
.TP
.IB MGSNAME := MGSNODE\fR[ : MGSNODE \fR]
The
.I MGSNAME
may be a colon-separated list of
.I MGSNODE
servers where the MGS service may run. Multiple
.I MGSNODE
values can be specified if the MGS service is configured for High Availability
and may be running on any one of the nodes.
.TP
.IB MGSNODE := MGSNID\fR[ , MGSNID \fR]
Each
.I MGSNODE
may specify a comma-separated list of NIDs,
if there are different LNet interfaces for the same
.IR MGSNODE .
.TP
.IB MGSNID := HOST @ NETTYPE \c
.RI [ NET_NUMBER ]
Each
.I MGSNID
contains a hostname that can be resolved via the
.BR hosts (5)
name service in
.BR nsswitch.conf (5),
or a numeric IP, IB, or other address that does not need resolution.
The
.BI @ NETTYPE
is the LNet network type, such as
.BR @tcp ", " @o2ib 
or other supported LND type,
.B @tcp0
if unspecified.  The optional
.I NET_NUMBER
is the network number for that
.IR NETTYPE ,
or 0 if unspecified.
.TP
.I BLOCK_DEVICE
specifies the physical disk or ZFS dataset uses to start the target service
formatted by the
.BR mkfs.lustre (8)
command. The
.I BLOCK_DEVICE
may be specified using
.BI -L LABEL
to find the first block device with that label (e.g.
.BR testfs-MDT0000 ),
or by UUID using the
.BI -U UUID
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
.BR tune2fs (8)
or similar.
.TP
.I SERVER_MOUNTPOINT
is the directory where the target filesystem will be mounted,
but is only useful for
.BR df (1)
to show the current space usage, and
.BR ioctl (3)
for block device operations such as
.BR resize2fs (8)
or
.BR fstrim (8).
It appears in
.BR /proc/mounts
to show that
.I BLOCK_DEVICE
is in use.
.PP
After successful mount, Lustre clients may have additional parameters set
according to those listed in
.BR /etc/lustre/mount.client.params ,
and/or the
.BI /etc/lustre/mount. FSNAME .params
files, with lines in the same style as command-line arguments to
.BR lctl-set_param (8),
with the form
.IR PARAM = VALUE .
.SH OPTIONS
.TP
.BI mgssec= FLAVOR
Specifies the encryption flavour for the initial network RPC connection to
the MGS node.
.IP
Non-security flavors are:
.BR null ,
.BR plain ,
and
.BR gssnull ,
which respectively disable, or have no encryption or integrity features for
testing purposes.
.IP
Kerberos flavors are:
.BR krb5n ,
.BR krb5a ,
.BR krb5i ,
and
.BR krb5p .
.IP
Shared-secret key flavors are:
.BR skn ,
.BR ska ,
.BR ski ,
and
.BR skpi .
.IP
See
.BR lgss_sk (8)
for more details. The security flavour for client-to-server connections is
specified in the filesystem configuration that the client fetches from the MGS.
.TP
.BI skpath= FILE \fR| DIRECTORY
Path to a file or directory with the keyfile(s) to load for this mount command.
Keys are inserted into the KEY_SPEC_SESSION_KEYRING keyring with a description
containing "lustre:" and a suffix which depends on whether the context of the
mount command is for an MGS, MDT/OST, or client.
If no
.B skpath
is specified for client mounts, the mount command will automatically check for
a keyfile named
.B .lgss
in the mount point directory and load it if present.
This option is only available when built with --enable-gss.
.TP
.BI exclude= OSTLIST
Start a client or MDT with a (colon-separated) list of known inactive OSTs.
.SS CLIENT OPTIONS
In addition to the standard options listed in
.BR mount (8),
Lustre understands the following
.B client-specific
options:
.TP
.B flock
Enable full distributed
.BR 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.
.TP
.B localflock
Enable local
.BR flock (2)
support, using only client-local file locking. This is faster than mounting
with the
.B flock
option, and can be used for applications that depend on functioning
.BR flock (2)
but run only on a single node.
.TP
.B noflock
Disables
.BR flock (2)
support entirely. Applications calling
.BR flock (2)
will get an
.B ENOSYS
error. It is possible to mount clients with different options,
and only those mounted with
.B flock
will be coherent amongst each other.
.TP
.B lazystatfs
Allows
.BR statfs (2)
(as used by
.BR df (1)
and
.BR 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.
.TP
.B nolazystatfs
Requires that
.BR statfs (2)
block until all OSTs and MDTs are available and have returned space usage.
.TP
.B user_xattr
Enable get/set of extended attributes by regular users. See the
.BR attr (5)
manual page.
.TP
.B nouser_xattr
Disable use of extended attributes by regular users.
Root and system processes can still use extended attributes.
.TP
.B always_ping
Force a client to keep pinging even if servers have enabled suppress_pings.
.TP
.B verbose
Enable mount/remount/umount console messages.
.TP
.B noverbose
Disable mount/remount/umount console messages.
.TP
.B user_fid2path
Enable FID to path translation by regular users via
.BR "lfs fid2path" .
.TP
.B 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.
.TP
.BI 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.
.IP
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.
.TP
.BI mgsname= MGSNAME
Specify a custom hostname for the MGS that will be displayed in
.BR /proc/mounts
instead of the resolved IP address. The network type (e.g.,
.BR @tcp ,
.BR @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.
.TP
.B test_dummy_encryption
Enable test dummy encryption mode.
.RE
.TP
.BI 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
.TP
.BI 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.
.SS SERVER OPTIONS
In addition to the standard mount options and backing disk type
(e.g. ldiskfs) options listed in
.BR mount (8),
Lustre understands the following
.B server-specific
options:
.TP
.BI acl
Enable POSIX Access Control List support for all clients. See the
.BR acl (5)
manual page.
.TP
.BI 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
.BI "'lctl set_param obdfilter." FSNAME -OST XXXX ".no_create=0'"
or
.BI "'lctl set_param mdt." FSNAME -MDT XXXX ".no_create=0'"
on the appropriate server node.
.BR 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
be read, modified, or deleted. If the OST or MDT is new then
it will not have any objects on it yet.
.TP
.BI nosvc
Only start the MGC (and MGS, if co-located) for a target service,
and not the actual MDS or OSS service.
.TP
.BI 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.
.TP
.BI nomgs
Start an MDT with a co-located MGS without starting the MGS service.
.TP
.BI noscrub
Do not trigger OI scrub automatically when an inconsistency is detected.
It is still possible to start explicitly using the
.BR "lctl lfsck_start" .
.TP
.BI skip_lfsck
Do not resume the former paused/crashed LFSCK automatically when mounting.
.TP
.BI abort_recov
Abort client recovery and start the target service immediately.
.TP
.BI md_stripe_cache_size= cache_size
Sets the MD RAID 'stripe_cache_size' parameter to
.I cache_size
KiB for server OST or MDT block device with a striped RAID configuration.
.TP
.BI recovery_time_soft= timeout
Allow
.I 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).
.TP
.BI 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).
.SH COMMAND-LINE OPTIONS
Some command-line options for
.B mount.lustre
itself may passed from the
.BR mount (8)
command-line, but are mostly only available for debugging if the
.BR mount.lustre (8)
command is run directly.
These are separate from the mountpoint options passed to
.BR mount (2)
for the mountpoint itself, which are listed in the
.B OPTIONS
section.
.TP
.BR -f ", " --fake
Fake filesystem mount, setting client-specific parameters and adding it to
.B /etc/fstab
without actually calling the
.BR mount (2)
system call.  Together with the
.B -v
option this will show what mount options would be set for the filesystem.
.TP
.BR --force
Force mounting the filesystem even if it appears to already be mounted.
.TP
.BR -h ", " --help
Print usage message and exit.
.TP
.BR -n ", " --nomtab
Do not update the
.B /etc/fstab
file after the mount has successfully completed.
.TP
.BR -o ", " --options
Specify the list of
.B OPTIONS
to pass to the kernel for
.IR MOUNTPOINT .
These are normally passed from the
.BR mount
command, but can be specified directly for debugging purposes.
.TP
.BR -v ", " --verbose
Print extra information during mounting.  This will be passed on from
.BR mount .
.TP
.BR -V ", " --version
Print the build version of the
.BR mount.lustre
binary and exit.
.SH BUGS
Not very many mount options can be changed with
.BR "-o remount" .
.SH EXAMPLES
Start a client for the Lustre filesystem
.B testfs
at the mount point
.BR /mnt/myfilesystem .
The Management Service is running on a node reachable via NID
.BR cfs21@tcp0 :
.RS
.EX
.RB client# " mount -t lustre cfs21@tcp0:/testfs /mnt/myfilesystem"
.EE
.RE
.PP
Like above example, but mount subdirectory
.B dir
as fileset:
.RS
.EX
.RB client# " mount -t lustre cfs21@tcp0:/testfs/dir /mnt/myfilesystem"
.EE
.RE
.PP
Like above example, but the Management Service is running on one of the service
nodes
.B mgs1
and
.BR mgs2 ,
are two different hosts separated by a colon and served as a failover pair,
and have both TCP and IB addresses.
Lustre tries the first one, and if that fails, it tries the second one.
On each service node, the comma-separated NIDs refer to
different interfaces on the same host, and the Lustre client chooses the best
one for communication based on which network interfaces are available locally:
.RS
.EX
.RB client# " mount -t lustre mgs1@tcp0,mgs1ib@o2ib0:mgs2@tcp0,mgs2ib@o2ib0:/testfs /mnt/fs"
.EE
.RE
.PP
Start the Lustre metadata target service from
.B /dev/sda1
on mountpoint
.BR /mnt/test/mdt :
.RS
.EX
.RB mds# " mount -t lustre_tgt /dev/sda1 /mnt/test/mdt"
.EE
.RE
.PP
Start the
.B testfs-MDT0000
service (by using the disk label), but aborts the Lustre client recovery
process for the case that clients are known to be unavailable:
.RS
.EX
.RB mds# " mount -t lustre_tgt -L testfs-MDT0000 -o abort_recov /mnt/test/mdt"
.EE
.RE
.PP
Mount a client filesystem with a custom MGS name for display purposes.
The network type
.B @o2ib
will be automatically appended to the MGS hostname
.B cfs-mgs
in
.BR /proc/mounts :
.RS
.EX
.RB client# " mount -t lustre -o mgsname=cfs-mgs@o2ib 10.0.0.2@o2ib,10.0.0.4@o2ib:/testfs /myfs"
.EE
.RE
.PP
Mount a client filesystem with automatic MGS name generation. The hostname
.B test-mgs
will be automatically extracted from the device string and
.B mgsname=test-mgs@tcp
will be appended to the list of mount options for display in
.BR /proc/mounts :
.RS
.EX
.RB client# " mount -t lustre test-mgs@o2ib:/testfs /mnt/myfs"
.EE
.RE
.SH AVAILABILITY
.B mount.lustre
and
.B mount.lustre_tgt
are part of the
.BR lustre (7)
filesystem package.
.B mount.lustre
was added in release 0.10.0, and
.\" Added in commit 0.9.1
.B mount.lustre_tgt
was added in release 2.13.0.
.\" Added in commit v2_12_58-71-g510aea4a37
.SH SEE ALSO
.BR lfs (1),
.BR lustre (7),
.BR lctl-set_param (8),
.BR mkfs.lustre (8),
.BR mount (8),
.BR tunefs.lustre (8)