Merge "LU-9771 flr: Merge branch 'flr'"

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

diff --git a/lustre/doc/mkfs.lustre.8 b/lustre/doc/mkfs.lustre.8
index a189849..9b2245c 100644 (file)
--- a/lustre/doc/mkfs.lustre.8
+++ b/lustre/doc/mkfs.lustre.8
@@ -1,21 +1,35 @@
 .\" -*- 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, Intel Corporation.
+.\" Copyright (c) 2011, 2016, 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.
 .\"

-.TH mkfs.lustre 8 "2008 Mar 15" Lustre "configuration utilities"
+.TH mkfs.lustre 8 "2014 Jun 10" Lustre "configuration utilities"

 .SH NAME
 mkfs.lustre \- format a disk for a Lustre service
 .SH SYNOPSIS
 .br
 .SH NAME
 mkfs.lustre \- format a disk for a Lustre service
 .SH SYNOPSIS
 .br

-.BR mkfs.lustre { --ost | --mdt | --mgs }
-.I [options] 
+.B mkfs.lustre
+.RB { --ost | --mdt | --mgs }
+.BR --fsname= <\fIname\fR>
+.RI [ options ]

 .I device
 .br
 .I device
 .br

-.B <target_type>
-is one of
+.B mkfs.lustre
+.RB { --ost | --mdt | --mgs }
+.B --backfstype=zfs
+.BR --fsname= <\fIname\fR>
+.RI [ options "] <" pool_name >/< dataset_name "> [<" zpool_specification >]
+
+.SH DESCRIPTION
+.B mkfs.lustre
+is used to format a disk device for use as part of a Lustre
+filesystem. After formatting, a disk can be mounted with
+.B mount -t lustre ...
+to start the Lustre service defined by this command.
+
+.SH OPTIONS

 .TP
 .BI \--ost
 object storage target
 .TP
 .BI \--ost
 object storage target


@@ -24,20 +38,25 @@ object storage target
 metadata storage target
 .TP
 .BI \--mgs
 metadata storage target
 .TP
 .BI \--mgs

-configuration management service - one per site.  This service can be
-combined with one 
+configuration management service, one per site or filesystem.  This service can
+be combined with one

 .BI \--mdt
 .BI \--mdt

-service by specifying both types
-.SH DESCRIPTION
-.B mkfs.lustre
-is used to format a disk device for use as part of a Lustre
-filesystem. After formatting, a disk can be mounted to start the Lustre
-service defined by this command.
-
-.SH OPTIONS
+service by specifying both types.

 .TP
 .BI \--backfstype= fstype
 .TP
 .BI \--backfstype= fstype

-Force a particular format for the backing fs (ext3, ldiskfs)
+Force a particular format for the backing fs (ldiskfs, zfs).
+.br
+.IR zpool_specification " = [[<" vdev_type ">] <" device "> [<" device "> ...] [<" vdev_type ">] ...]"
+.br
+.IR vdev_type " ="
+.RB { mirror , raidz , raidz2 , raidz3 , cache }
+.br
+.IR device " = { " "Linux block device" " }"
+
+If no vdev_type is given, then the devices are used in a round-robin
+(striped) manner. See
+.BR zpool (8)
+for more details.

 .TP
 .BI \--comment= comment
 Set user comment about this disk, ignored by Lustre.
 .TP
 .BI \--comment= comment
 Set user comment about this disk, ignored by Lustre.


@@ -48,7 +67,7 @@ Set device size for loop devices
 .BI \--dryrun
 Only print what would be done; does not affect the disk
 .TP
 .BI \--dryrun
 Only print what would be done; does not affect the disk
 .TP

-.BI \--failnode= nid,...  
+.BI \--failnode= nid,...

 Set the NID(s) of a failover partner. This option can be repeated as desired.
 Cannot be used with --servicenode.
 .TP
 Set the NID(s) of a failover partner. This option can be repeated as desired.
 Cannot be used with --servicenode.
 .TP


@@ -56,18 +75,20 @@ Cannot be used with --servicenode.
 Set the NID(s) of all service partner. This option treats all nodes as equal
 service nodes. Cannot be used with --failnode.
 .TP
 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  
-The Lustre filesystem this service will be part of.  The maximum
-filesystem_name length is 8 characters. Default is 'lustre'
+.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.

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

-Force a particular OST or MDT index 
+Specify a particular OST or MDT index. Required for all targets other than the MGS.
+The index parameter may either be a decimal number or a hexadecimal number
+starting with '0x'.

 .TP
 .BI \--mkfsoptions= opts
 Format options for the backing fs. For example, ext3 options could be set here.
 .TP
 .BI \--mountfsoptions= opts
 .TP
 .BI \--mkfsoptions= opts
 Format options for the backing fs. For example, ext3 options could be set here.
 .TP
 .BI \--mountfsoptions= opts

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

 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.


@@ -76,18 +97,21 @@ 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,...
 Network(s) to restrict this ost/mdt to. This option can be repeated as desired.
 .TP
 .BI \--network= net,...
 Network(s) to restrict this ost/mdt to. This option can be repeated as desired.
 .TP

-.BI \--mgsnode= nid,...  
+.BI \--mgsnode= nid,...

 Set the NID(s) of the MGS node, required for all targets other than the MGS.
 .TP
 .BI \--param " key=value"
 Set the NID(s) of the MGS node, required for all targets other than the MGS.
 .TP
 .BI \--param " key=value"

-Set permanent parameter 
-.I key 
-to value 
+Set permanent parameter
+.I key
+to value

 .IR 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


@@ -97,11 +121,11 @@ System obd timeout
 .RS
 Default stripe size
 .RE
 .RS
 Default stripe size
 .RE

-.I \--param lov.stripecount=2       
+.I \--param lov.stripecount=2

 .RS
 Default stripe count
 .RE
 .RS
 Default stripe count
 .RE

-.I \--param failover.mode=failout    
+.I \--param failover.mode=failout

 .RS
 Return errors instead of waiting for recovery
 .RE
 .RS
 Return errors instead of waiting for recovery
 .RE


@@ -110,37 +134,77 @@ Return errors instead of waiting for recovery
 .BI \--quiet
 Print less information.
 .TP
 .BI \--quiet
 Print less information.
 .TP

-.BI \--reformat 
-Reformat an existing Lustre disk
+.BI \--reformat
+Reformat an existing Lustre disk as a new target
+.TP
+.BI \--replace
+Used to initialize a target with the same
+.I --index
+as a previously used target if the old target was permanently lost for
+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
 Used for optizing MDT inode size
 .TP
 .TP
 .BI \--stripe-count-hint= stripes
 Used for optizing MDT inode size
 .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.
 .BI \--verbose
 Print more information.

+.TP
+.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
 
 .SH EXAMPLES
 .TP

-.B mkfs.lustre --fsname=testfs --mdt --mgs /dev/sda1
+.B mkfs.lustre --fsname=testfs --index=0 --mdt --mgs /dev/sda1

 Combined MGS and MDT for filesystem 'testfs' on node e.g. cfs21
 .TP
 Combined MGS and MDT for filesystem 'testfs' on node e.g. cfs21
 .TP

-.B mkfs.lustre --fsname=testfs --ost --mgsnode=cfs21@tcp0 /dev/sdb
+.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
 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=0 --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

-.B mkfs.lustre --fsname=myfs1 --mdt --mgsnode=cfs22@tcp0 /dev/sda2
+.B mkfs.lustre --fsname=myfs1 --index=0 --mdt --mgsnode=cfs22@tcp0 /dev/sda2

 MDT for filesystem 'myfs1' on any node, using the above MGS
 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'.

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

-is part of the 
-.BR Lustre (7) 
+is part of the
+.BR lustre (7)

 filesystem package.
 .SH SEE ALSO
 .BR lustre (7),
 .BR mount.lustre (8),
 .BR tunefs.lustre (8),
 .BR lctl (8),
 filesystem package.
 .SH SEE ALSO
 .BR lustre (7),
 .BR mount.lustre (8),
 .BR tunefs.lustre (8),
 .BR lctl (8),

-.BR lfs (1)
+.BR lfs (1),
+.BR zpool (8)