lustre/doc/mount.lustre.8

   1 .\" -*- nroff -*-
   2 .\" Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
   3 .\"
   4 .\" Copyright (c) 2012, 2017, Intel Corporation.
   5 .\"
   6 .\" This file may be copied under the terms of the GNU Public License v2.
   7 .\"
   8 .TH mount.lustre 8 "2019 Jul 30" Lustre "configuration utilities"
   9 .SH NAME
  10 mount.lustre \- mount helper for Lustre client
  11 mount.lustre_tgt \- mount helper for Lustre target service
  12 .SH SYNOPSIS
  13 .br
  14 .BI "mount -t lustre [-o " options "] " "<mgsname>:/<fsname> <client_mountpoint>"
  15 .br
  16 .BI "mount -t lustre_tgt [-o " options "] " "<block_device> <server_mountpoint>"
  17 .SH DESCRIPTION
  18 .B mount.lustre
  19 and
  20 .B mount.lustre_tgt
  21 are used to start a Lustre client or target service, respectively.  They
  22 should not be called directly; rather they are helper programs invoked through
  23 .BR mount (8)
  24 as above when the
  25 .B lustre
  26 or
  27 .B lustre_tgt
  28 filesystem type is used.  Lustre clients and targets are stopped by using the
  29 .BR umount (8)
  30 command.
  31 .br
  32
  33 There are two forms for the device option passed to the
  34 .I mount
  35 command, depending on whether a client or a target service is started:
  36 .TP
  37 .IR <mgsname> :/ <fsname>[/<subdir>]
  38 mounts the Lustre client filesystem named
  39 .I fsname
  40 (optionally starting at subdirectory
  41 .I subdir
  42 within the filesystem, if specified) on the client at the directory
  43 .IR client_mountpoint ,
  44 by contacting the Management Service at
  45 .IR mgsname .
  46 The format for
  47 .I mgsname
  48 is defined below.  A client filesystem will typically be listed in
  49 .BR fstab (5)
  50 for automatic mount at boot time, is usable like any local filesystem, and
  51 provides a full POSIX-compilant interface.
  52 .TP
  53 .I block_device
  54 specifies the phyisical disk or ZFS dataset uses to start the target service
  55 formatted by the
  56 .IR mkfs.lustre (8)
  57 command.  The
  58 .I block_device
  59 may be specified using
  60 .BI -L label
  61 to find the first block device with that label (e.g.
  62 .BR testfs-MDT0000 ),
  63 or by UUID using the
  64 .BI -U uuid
  65 option. Care should be taken if there is a device-level backup of
  66 the target filesystem, which would have a duplicate label and UUID if it is
  67 not changed with
  68 .BR tune2fs (8)
  69 or similar.  The mounted target service filesystem at
  70 .I mountpoint
  71 is only useful for
  72 .BR df (1)
  73 operations to show the current space usage, and appears in
  74 .BR /proc/mounts
  75 to show the device is in use.
  76 .SH OPTIONS
  77 .TP
  78 .BI <mgsname>:= <mgsnode>[:<mgsnode>]
  79 The
  80 .I mgsname
  81 may be a colon-separated list of
  82 .I mgsnode
  83 names where the MGS service may run.  Multiple
  84 .I mgsnode
  85 values can be specified if the MGS service is configures for HA failover
  86 and may be running on any one of the nodes.
  87 .TP
  88 .BI <mgsnode>:= <mgsnid>[,<mgsnid>]
  89 Each
  90 .I mgsnode
  91 may specify a comma-separated list of NIDs, if there are different
  92 LNet interfaces for the same
  93 .IR mgsnode .
  94 .TP
  95 .BI mgssec= flavor
  96 Specifies the encryption flavour for the initial network RPC connection to
  97 the MGS node.  Non-security flavors are:
  98 .BR null ,
  99 .BR plain ,
 100 and
 101 .BR gssnull ,
 102 which respectively disable, or have no encryption or integrity features for
 103 testing purposes.  Kerberos flavors are:
 104 .BR krb5n ,
 105 .BR krb5a ,
 106 .BR krb5i ,
 107 and
 108 .BR krb5p .
 109 Shared-secret key flavors are:
 110 .BR skn ,
 111 .BR ska ,
 112 .BR ski ,
 113 and
 114 .BR skpi ,
 115 see
 116 .BR lgss_sk (8)
 117 for more details.  The security flavour for client-to-server connections is
 118 specified in the filesystem configuration that the client fetches from the MGS.
 119 .TP
 120 .BI skpath= file|directory
 121 Path to a file or directory with the keyfile(s) to load for this mount command.
 122 Keys are inserted into the KEY_SPEC_SESSION_KEYRING keyring with a description
 123 containing "lustre:" and a suffix which depends on whether the context of the
 124 mount command is for an MGS, MDT/OST, or client.
 125 This option is only available when built with --enable-gss.
 126 .TP
 127 .BI exclude= ostlist
 128 Start a client or MDT with a (colon-separated) list of known inactive OSTs.
 129 .SH CLIENT OPTIONS
 130 In addition to the standard options listed in
 131 .BR mount (8),
 132 Lustre understands the following
 133 .B client-specific
 134 options:
 135 .TP
 136 .BI flock
 137 Enable full distributed
 138 .BI flock (2)
 139 support, coherent across all client nodes also using this mount option.  This
 140 is useful if applications need coherent userspace file locking across multiple
 141 client nodes, but also imposes communications overhead in order to maintain
 142 locking consistency between client nodes.
 143 .TP
 144 .BI localflock
 145 Enable local
 146 .BR flock (2)
 147 support, using only client-local file locking.  This is faster than mounting
 148 with the
 149 .B flock
 150 option, and can be used for applications that depend on functioning
 151 .BI flock (2)
 152 but run only on a single node.
 153 .TP
 154 .BI noflock
 155 Disables
 156 .BR flock(2)
 157 support entirely, and is the default option.  Applications calling
 158 .BR flock(2)
 159 will get an
 160 .B ENOSYS
 161 error.  It is up to the administrator to choose either the
 162 .B localflock
 163 or
 164 .B flock
 165 mount option based on their requirements.  It is possible to mount clients
 166 with different options, and only those mounted with
 167 .B flock
 168 will be coherent amongst each other.
 169 .TP
 170 .BI lazystatfs
 171 Allows
 172 .BR statfs (2)
 173 (as used by
 174 .BR df (1)
 175 and
 176 .BR lfs-df (1))
 177 to return even if some OST or MDT is unresponsive or has been temporarily
 178 or permanently disabled in the configuration.  This avoids blocking until
 179 all of the targets are available.  This is the default since Lustre 2.9.0.
 180 .TP
 181 .BI nolazystatfs
 182 Requires that
 183 .BR statfs (2)
 184 block until all OSTs and MDTs are available and have returned space usage.
 185 .TP
 186 .BI user_xattr
 187 Enable get/set of extended attributes by regular users.  See the
 188 .BR attr (5)
 189 manual page.
 190 .TP
 191 .BI nouser_xattr
 192 Disable use of extended attributes by regular users.  Root and system processes can still use extended attributes.
 193 .TP
 194 .BI always_ping
 195 Force a client to keep pinging even if servers have enabled suppress_pings.
 196 .TP
 197 .BI verbose
 198 Enable mount/remount/umount console messages.
 199 .TP
 200 .BI noverbose
 201 Disable mount/remount/umount console messages.
 202 .TP
 203 .BI user_fid2path
 204 Enable FID to path translation by regular users via
 205 .BR "lfs fid2path" .
 206 .TP
 207 .BI nouser_fid2path
 208 Disable FID to path translation by regular users.  Root and process with
 209 CAP_DAC_READ_SEARCH can still perform FID to path translation.
 210 .TP
 211 .BI network= net
 212 Limit connections from the client to be on the network NID specified by 'net'.
 213 \'net\' designates a single network NID, like 'o2ib2' or 'tcp1'.
 214 This option can be useful in case of several Lustre client mount
 215 points on the same node, with each mount point using a different
 216 network. It is also interesting when running Lustre clients from
 217 containers, by restricting each container to a specific network.
 218 .PP
 219 .RS
 220 Warning! 'network' option is incompatible with LNet Dynamic Peer Discovery.
 221 If you want to restrict client NID, please make sure LNet Dynamic Peer Discovery
 222 is disabled.
 223 .RE
 224 .TP
 225 .BI test_dummy_encryption
 226 Enable test dummy encryption mode.
 227 .RE
 228 .TP
 229 .BI noencrypt
 230 Disable Lustre client-side encryption. By default, Lustre client-side encryption
 231 is enabled, letting users define encryption policies on a per-directory basis.
 232 fscrypt userspace tool can be used for that purpose, see
 233 https://github.com/google/fscrypt
 234 .SH SERVER OPTIONS
 235 In addition to the standard mount options and backing disk type
 236 (e.g. ldiskfs) options listed in
 237 .BR mount (8),
 238 Lustre understands the following
 239 .B server-specific
 240 options:
 241 .TP
 242 .BI acl
 243 Enable POSIX Access Control List support for all clients.  See the
 244 .BR acl (5)
 245 manual page.
 246 .TP
 247 .BI no_precreate
 248 Do not allow objects to be created on the OST after mounting.  This
 249 allows a (potentially newly-formatted) OST to be started without
 250 clients starting to use it immediately.  To allow the MDS to create
 251 objects on the OST mount without this option, or run
 252 .BI "lctl set_param obdfilter." fsname -OST nnnn .no_precreate=0
 253 on the OSS to re-enable object creation.
 254 .BR NOTE :
 255 this does not start the OST read-only, it only disables the
 256 creation of new objects on the OST.  This means existing objects
 257 can be read, modified, or deleted, but if the OST is new then it
 258 will not have any such objects.
 259 .TP
 260 .BI nosvc
 261 Only start the MGC (and MGS, if co-located) for a target service,
 262 and not the actual MDS or OSS service.
 263 .TP
 264 .BI nomgs
 265 Start an MDT with a co-located MGS without starting the MGS service.
 266 .TP
 267 .BI noscrub
 268 Do not trigger OI scrub automatically when an inconsistency is detected.
 269 It is still possible to start explicitly using the
 270 .BR "lctl lfsck_start" .
 271 .TP
 272 .BI skip_lfsck
 273 Do not resume the former paused/crashed LFSCK automatically when mounting.
 274 .TP
 275 .BI abort_recov
 276 Abort client recovery and start the target service immediately.
 277 .TP
 278 .BI md_stripe_cache_size
 279 Sets the stripe cache size for server side disk with a striped raid
 280 configuration.
 281 .TP
 282 .BI max_sectors_kb
 283 Automatically Sets the block device parameter of 'max_sectors_kb' for the
 284 MDT or OST target. When max_sectors_kb isn't specified, that parameter for
 285 block device will be set to same as it's own 'max_hw_sectors_kb' (up to a
 286 maximum of 16M), this is default behavior suited for most users. When
 287 max_sectors_kb is specified as zero, the old parameter value will be kept.
 288 When max_sectors_kb is specified as a positive number, the parameter will
 289 be set to this number arbitrarily.
 290 .TP
 291 .BI recovery_time_soft= timeout
 292 Allow 'timeout' seconds for clients to reconnect for recovery after a server
 293 crash.  This timeout will be incrementally extended if it is about to expire
 294 and the server is still handling new connections from recoverable clients.
 295 The default soft recovery timeout is set to 300 seconds (5 minutes).
 296 .TP
 297 .BI recovery_time_hard= timeout
 298 The server will be allowed to incrementally extend its timeout up to a hard
 299 maximum of 'timeout' seconds.  The default hard recovery timeout is set to
 300 900 seconds (15 minutes).
 301 .SH EXAMPLES
 302 .TP
 303 .B mount -t lustre cfs21@tcp0:/testfs /mnt/myfilesystem
 304 Start a client for the Lustre filesystem
 305 .B testfs
 306 at the mount point
 307 .BR /mnt/myfilesystem .
 308 The Management Service is running on a node reachable via NID
 309 .BR cfs21@tcp0 .
 310 .TP
 311 .B mount -t lustre cfs21@tcp0:/testfs/dir /mnt/myfilesystem
 312 Like above example, but mount subdirectory
 313 .B dir
 314 as fileset.
 315 .TP
 316 .B mount -t lustre mgs1@tcp0,mgs1ib@o2ib0:mgs2@tcp0,mgs2ib@o2ib0:/testfs /mnt/fs
 317 Like above example, but the Management Service is running on one of the service
 318 nodes
 319 .B mgs1
 320 and
 321 .B mgs2, which are two different hosts separated by a colon and
 322 served as a failover pair. Lustre tries the first one, and if that fails, it
 323 tries the second one. On each service node, the comma-separated NIDs refer to
 324 different interfaces on the same host, and the Lustre client chooses the best
 325 one for communication based on which network interfaces are available locally.
 326 .TP
 327 .B mount -t lustre_tgt /dev/sda1 /mnt/test/mdt
 328 Start the Lustre metadata target service from
 329 .B /dev/sda1
 330 on mountpoint
 331 .BR /mnt/test/mdt .
 332 .TP
 333 .B mount -t lustre_tgt -L testfs-MDT0000 -o abort_recov /mnt/test/mdt
 334 Start the
 335 .B testfs-MDT0000
 336 service (by using the disk label), but aborts the Lustre client recovery
 337 process for the case that clients are known to be unavailable.
 338 .SH BUGS
 339 Not very many mount options can be changed with
 340 .BR "-o remount" .
 341 .SH AVAILABILITY
 342 .B mount.lustre
 343 is part of the
 344 .BR Lustre (7)
 345 filesystem package.
 346 .SH SEE ALSO
 347 .BR lustre (7),
 348 .BR mount (8),
 349 .BR mkfs.lustre (8),
 350 .BR tunefs.lustre (8),
 351 .BR lctl (8),
 352 .BR lfs (1)