LU-12616 obclass: fix MDS start/stop race

[fs/lustre-release.git] / lustre / doc / mkfs.lustre.8

diff --git a/lustre/doc/mkfs.lustre.8 b/lustre/doc/mkfs.lustre.8
index a9a879f..73ffab1 100644 (file)
--- a/lustre/doc/mkfs.lustre.8
+++ b/lustre/doc/mkfs.lustre.8
@@ -1,7 +1,7 @@
 .\" -*- nroff -*-
 .\" Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
 .\"
 .\" -*- nroff -*-
 .\" Copyright (c) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
 .\"

-.\" Copyright (c) 2011, 2012, 2014, Intel Corporation.
+.\" Copyright (c) 2011, 2017, Intel Corporation.

 .\"
 .\" This file may be copied under the terms of the GNU Public License.
 .\"
 .\"
 .\" This file may be copied under the terms of the GNU Public License.
 .\"


@@ -76,17 +76,39 @@ Set the NID(s) of all service partner. This option treats all nodes as equal
 service nodes. Cannot be used with --failnode.
 .TP
 .BI \--fsname= filesystem_name
 service nodes. Cannot be used with --failnode.
 .TP
 .BI \--fsname= filesystem_name

-The Lustre filesystem this service will be part of. The maximum filesystem_name
-length is 8 characters. Required for all targets other than MGS.
+The Lustre filesystem this target will be part of. Valid
+.IR filesystem_name s
+are between 1 and 8 characters long and must only use upper- and lower-case
+English letters, numbers, and '\-', or '_' (regexp [-_a\-zA\-Z0\-9]).  All
+targets in a single filesystem must specify the same
+.IR filesystem_name ,
+and it must be unique between all filesystems mounted by a single client
+at one time.  Using "lustre" as the filesystem name is discouraged, to avoid
+future problems if a client needs to mount two such filesystems, and to
+reduce confusion for administrators/users between "lustre" as the
+.I filesystem_name
+and "lustre" as the literal string that must be used in places for the
+.BR filesystem_type .
+The
+.B \--fsname
+option is not valid for the MGS, since it may be used for multiple filesystems.

 .TP
 .BI \--index= index
 .TP
 .BI \--index= index

-Specify a particular OST or MDT index. Required for all targets other than the MGS.
+Specify a particular OST or MDT index. Required for all targets other than
+the MGS, and must be unique for all targets in the same filesystem. Typically
+sequential values starting from 0 are used.  The index parameter may either
+be a decimal number, or a hexadecimal number starting with '0x'.

 .TP
 .BI \--mkfsoptions= opts
 .TP
 .BI \--mkfsoptions= opts

-Format options for the backing fs. For example, ext3 options could be set here.
+Additional formatting options passed through to the backing filesystem. For
+example, options for
+.B mke2fs
+or
+.B zpool
+could be set here.

 .TP
 .BI \--mountfsoptions= opts
 .TP
 .BI \--mountfsoptions= opts

-Set the mount options that will be used when mounting the backing fs.
+Set persistent mount options that will be used when mounting Lustre targets.

 WARNING: unlike earlier versions of \fBmkfs.lustre\fR, this version completely
 replaces the default mount options with those specified on the command line,
 issuing a warning on stderr if any of the default mount options are omitted.
 WARNING: unlike earlier versions of \fBmkfs.lustre\fR, this version completely
 replaces the default mount options with those specified on the command line,
 issuing a warning on stderr if any of the default mount options are omitted.


@@ -95,8 +117,11 @@ OST: \fIerrors=remount-ro,mballoc,extents\fR;
 MGS/MDT: \fIerrors=remount-ro,user_xattr\fR.
 \fBDO NOT\fR alter the default mount options unless you know what you are doing.
 .TP
 MGS/MDT: \fIerrors=remount-ro,user_xattr\fR.
 \fBDO NOT\fR alter the default mount options unless you know what you are doing.
 .TP

+.BI \--backfs-mount-opts=opts
+Use these options for mounting backing fs while mkfs.lustre is working.
+.TP

 .BI \--network= net,...
 .BI \--network= net,...

-Network(s) to restrict this ost/mdt to. This option can be repeated as desired.
+Network(s) to restrict this OST/MDT to. This option can be repeated as desired.

 .TP
 .BI \--mgsnode= nid,...
 Set the NID(s) of the MGS node, required for all targets other than the MGS.
 .TP
 .BI \--mgsnode= nid,...
 Set the NID(s) of the MGS node, required for all targets other than the MGS.


@@ -106,7 +131,7 @@ Set permanent parameter
 .I key
 to value
 .IR value .
 .I key
 to value
 .IR value .

-This option can be repeated as desired.  Typical options might include:
+This option can be repeated as desired. Typical options might include:

 .RS
 .I \--param sys.timeout=40
 .RS
 .RS
 .I \--param sys.timeout=40
 .RS


@@ -140,7 +165,15 @@ some reason (e.g. multiple disk failure or massive corruption).  This
 avoids having the target try to register as a new target with the MGS.
 .TP
 .BI \--stripe-count-hint= stripes
 avoids having the target try to register as a new target with the MGS.
 .TP
 .BI \--stripe-count-hint= stripes

-Used for optizing MDT inode size
+Specify the expected common number of stripes on a file so that the MDT
+inode size can be optimized for the typical use case.
+.TP
+.BI \--force-nohostid
+Ignore unset hostid for ZFS import protection. To set hostid either set
+spl_hostid parameter for spl.ko or set /etc/hostid, see zgenhostid(8).  To
+populate the spl_hostid parameter, spl.ko must be (re)loaded after /etc/hostid
+is created.
+

 .TP
 .BI \--verbose
 Print more information.
 .TP
 .BI \--verbose
 Print more information.


@@ -148,6 +181,17 @@ Print more information.
 .BI \--version
 Output build version of the mkfs.lustre utiltiy.
 
 .BI \--version
 Output build version of the mkfs.lustre utiltiy.
 

+.SH NID
+A Lustre network identifier (NID) is used to uniquely identify a Lustre network
+endpoint by node ID and network type. The format of the NID is:
+\fInetwork_id@network_type\fR.
+If a node has multiple network interfaces, it may have multiple NIDs, which must
+all be identified so other nodes can choose the NID that is appropriate for
+their network interfaces. Typically, NIDs are specified in a list delimited by
+commas (,). However, when failover nodes are specified, the NIDs are delimited
+by a colon (:) or by repeating a keyword such as \fI--mgsnode=\fR or
+\fI--servicenode=\fR.
+

 .SH EXAMPLES
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs /dev/sda1
 .SH EXAMPLES
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs /dev/sda1


@@ -156,6 +200,13 @@ Combined MGS and MDT for filesystem 'testfs' on node e.g. cfs21
 .B mkfs.lustre --fsname=testfs --index=0 --ost --mgsnode=cfs21@tcp0 /dev/sdb
 OST for filesystem 'testfs' on any node using the above MGS.
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --ost --mgsnode=cfs21@tcp0 /dev/sdb
 OST for filesystem 'testfs' on any node using the above MGS.
 .TP

+.B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs --servicenode=cfs21@tcp0,cfs21ib@o2ib0 --servicenode=cfs22@tcp0,cfs22ib@o2ib0 /dev/sda1
+Combined MGS and MDT for filesystem 'testfs' on failover pair cfs21 and cfs22.
+.TP
+.B mkfs.lustre --fsname=testfs --index=1 --ost --mgsnode=cfs21@tcp0,cfs21ib@o2ib0:cfs22@tcp0,cfs22ib@o2ib0 --failnode=cfs24@tcp0,cfs24ib@o2ib0 /dev/sdb
+OST for filesystem 'testfs' using the above MGS and having a failover partner
+cfs24.
+.TP

 .B mkfs.lustre --mgs /dev/sda1
 Standalone MGS on e.g. node cfs22
 .TP
 .B mkfs.lustre --mgs /dev/sda1
 Standalone MGS on e.g. node cfs22
 .TP


@@ -163,8 +214,8 @@ Standalone MGS on e.g. node cfs22
 MDT for filesystem 'myfs1' on any node, using the above MGS
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs zfspool/mdt1 mirror /dev/sdb /dev/sdc mirror /dev/sdd /dev/sde
 MDT for filesystem 'myfs1' on any node, using the above MGS
 .TP
 .B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs zfspool/mdt1 mirror /dev/sdb /dev/sdc mirror /dev/sdd /dev/sde

-Create zfs pool 'zfspool' on two root vdevs each a mirror of two disks and create mdt/mgs on
-filesystem 'zfspool/mdt1'.
+Create zfs pool 'zfspool' on two root vdevs each a mirror of two disks and
+create mdt/mgs on filesystem 'zfspool/mdt1'.

 
 .SH AVAILABILITY
 .B mkfs.lustre
 
 .SH AVAILABILITY
 .B mkfs.lustre


@@ -172,9 +223,10 @@ is part of the
 .BR lustre (7)
 filesystem package.
 .SH SEE ALSO
 .BR lustre (7)
 filesystem package.
 .SH SEE ALSO

+.BR lctl (8),
+.BR lfs (1),

 .BR lustre (7),
 .BR lustre (7),

+.BR mke2fs (8),

 .BR mount.lustre (8),
 .BR tunefs.lustre (8),
 .BR mount.lustre (8),
 .BR tunefs.lustre (8),

-.BR lctl (8),
-.BR lfs (1),

 .BR zpool (8)
 .BR zpool (8)