6253 F_GETLK doesn't always return lock owner

[illumos-gate.git] / usr / src / man / man1m / metainit.1m

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH METAINIT 1M "Mar 27, 2006"
.SH NAME
metainit \- configure metadevices
.SH SYNOPSIS
.LP
.nf
\fB/sbin/metainit\fR \fB-h\fR
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fIconcat/stripe\fR \fInumstripes\fR \fIwidth\fR
     \fIcomponent...\fR [\fB-i\fR \fIinterlace\fR]
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIwidth\fR \fIcomponent...\fR [\fB-i\fR \fIinterlace\fR]]
     [\fB-h\fR \fIhot_spare_pool\fR]
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fImirror\fR \fB-m\fR \fIsubmirror\fR
     [\fIread_options\fR] [\fIwrite_options\fR]
     [\fIpass_num\fR]
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fIRAID\fR \fB-r\fR \fIcomponent...\fR
     [\fB-i\fR \fIinterlace\fR]
     [\fB-h\fR \fIhot_spare_pool\fR] [\fB-k\fR] [\fB-o\fR \fIoriginal_column_count\fR]
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fIhot_spare_pool\fR
     [\fIhotspare...\fR]
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fImetadevice-name\fR
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fB-a\fR
.fi

.LP
.nf
\fB/sbin/metainit\fR [\fIgeneric options\fR] \fIsoftpart\fR \fB-p\fR [\fB-e\fR] \fIcomponent\fR
     [\fB-A\fR \fIalignment\fR] \fIsize\fR
.fi

.LP
.nf
\fB/sbin/metainit\fR \fB-r\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBmetainit\fR command configures metadevices and hot spares according to
the information specified on the command line. Alternatively, you can run
\fBmetainit\fR so that it uses configuration entries you specify in the
\fB/etc/lvm/md.tab\fR file (see \fBmd.tab\fR(4)). All metadevices must be set
up by the \fBmetainit\fR command before they can be used.
.sp
.LP
Solaris Volume Manager supports storage devices and logical volumes greater
than 1 terabyte (TB) when a system runs a 64-bit Solaris kernel. Support for
large volumes is automatic. If a device greater than 1 TB is created, Solaris
Volume Manager configures it appropriately and without user intervention.
.sp
.LP
If a system with large volumes is rebooted under a 32-bit Solaris kernel, the
large volumes are visible through \fBmetastat\fR output. Large volumes cannot
be accessed, modified or deleted, and no new large volumes can be created. Any
volumes or file systems on a large volume in this situation are unavailable. If
a system with large volumes is rebooted under a version of Solaris prior to the
Solaris 9 4/03 release, Solaris Volume Manager does not start. You must remove
all large volumes before Solaris Volume Manager runs under an earlier version
of the Solaris Operating System.
.sp
.LP
If you edit the \fB/etc/lvm/md.tab\fR file to configure metadevices, specify
one complete configuration entry per line. You then run the \fBmetainit\fR
command with either the \fB-a\fR option, to activate all metadevices you
entered in the \fB/etc/lvm/md.tab\fR file, or with the metadevice name
corresponding to a specific configuration entry.
.sp
.LP
\fBmetainit\fR does not maintain the state of the volumes that would have been
created when \fBmetainit\fR is run with both the \fB-a\fR and \fB-n\fR flags.
Any volumes in \fBmd.tab\fR that have dependencies on other volumes in
\fBmd.tab\fR are reported as errors when \fBmetainit\fR \fB-a\fR \fB-n\fR is
run, although the operations might succeed when \fBmetainit\fR \fB-a\fR is run.
See \fBmd.tab\fR(4).
.sp
.LP
Solaris Volume Manager never updates the \fB/etc/lvm/md.tab\fR file. Complete
configuration information is stored in the metadevice state database, not
\fBmd.tab\fR. The only way information appears in \fBmd.tab\fR is through
editing it by hand.
.sp
.LP
When setting up a disk mirror, the \fBfirst\fR step is to use \fBmetainit\fR
create a one-on-one concatenation for the root slice. See \fBEXAMPLES\fR.
.SH OPTIONS
.sp
.LP
The following options are supported:
.SS "Generic Options"
.sp
.LP
Root privileges are required for all of the following options except \fB-h\fR.
.sp
.LP
The following generic options are supported:
.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.sp .6
.RS 4n
Forces the \fBmetainit\fR command to continue even if one of the slices
contains a mounted file system or is being used as \fBswap\fR, or if the stripe
being created is smaller in size than the underlying soft partition. This
option is required when configuring mirrors on root (\fB/\fR), \fBswap\fR, and
\fB/usr\fR.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.sp .6
.RS 4n
Displays usage message.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Checks the syntax of your command line or \fBmd.tab\fR entry without actually
setting up the metadevice. If used with \fB-a\fR, all devices are checked but
not initialized.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.sp .6
.RS 4n
Only used in a shell script at boot time. Sets up all metadevices that were
configured before the system crashed or was shut down. The information about
previously configured metadevices is stored in the metadevice state database
(see \fBmetadb\fR(1M)).
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fB\fIsetname\fR\fR\fR
.ad
.sp .6
.RS 4n
Specifies the name of the diskset on which \fBmetainit\fR works. Without the
\fB-s\fR option, the \fBmetainit\fR command operates on your local metadevices
and/or hotspares.
.RE

.SS "Concat/Stripe Options"
.sp
.LP
The following concat/stripe options are supported:
.sp
.ne 2
.na
\fB\fIconcat/stripe\fR\fR
.ad
.sp .6
.RS 4n
Specifies the metadevice name of the concatenation, stripe, or concatenation of
stripes being defined.
.RE

.sp
.ne 2
.na
\fB\fInumstripes\fR\fR
.ad
.sp .6
.RS 4n
Specifies the number of individual stripes in the metadevice. For a simple
stripe, \fInumstripes\fR is always 1. For a concatenation, \fInumstripes\fR is
equal to the number of slices. For a concatenation of stripes, \fInumstripes\fR
varies according to the number of stripes.
.RE

.sp
.ne 2
.na
\fB\fIwidth\fR\fR
.ad
.sp .6
.RS 4n
Specifies the number of slices that make up a stripe. When \fIwidth\fR is
greater than 1, the slices are striped.
.RE

.sp
.ne 2
.na
\fB\fIcomponent\fR\fR
.ad
.sp .6
.RS 4n
The logical name for the physical slice (partition) on a disk drive, such as
\fB/dev/dsk/c0t0d0s0\fR. For RAID level 5 metadevices, a minimum of three
slices is necessary to enable striping of the parity information across slices.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fB\fIinterlace\fR\fR\fR
.ad
.sp .6
.RS 4n
Specifies the interlace size. This value tells Solaris Volume Manager how much
data to place on a slice of a striped or RAID level 5 metadevice before moving
on to the next slice. \fIinterlace\fR is a specified value, followed by either
`\fBk\fR' for kilobytes, `\fBm\fR' for megabytes, or `\fBb\fR' for blocks. The
characters can be either uppercase or lowercase. The \fIinterlace\fR specified
cannot be less than 16 blocks, or greater than 100 megabytes. If
\fIinterlace\fR is not specified, it defaults to 512 kilobytes.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR \fB\fIhot_spare_pool\fR\fR\fR
.ad
.sp .6
.RS 4n
Specifies the \fIhot_spare_pool\fR to be associated with the metadevice. If you
use the command line, the hot spare pool must have been previously created by
the \fBmetainit\fR command before it can be associated with a metadevice. Use
\fB/-h\fR \fBhsp\fR\fInnn\fR when the concat/stripe being created is to be used
as a submirror.
.sp
Names for hot spare pools can be any legal file name that is composed of
alphanumeric characters, a dash ("-"), an underscore ("_"), or a period (".").
Names must begin with a letter. The words "all" and "none" are reserved and
cannot be used.
.RE

.SS "Mirror Options"
.sp
.LP
The following mirror options are supported:
.sp
.ne 2
.na
\fB\fImirror\fR \fB-m\fR \fI\fR\fIsubmirror\fR\fI\fR\fR
.ad
.sp .6
.RS 4n
Specifies the metadevice name of the mirror. The \fB-m\fR indicates that the
configuration is a mirror. \fIsubmirror\fR is a metadevice (stripe or
concatentation) that makes up the initial one-way mirror. Solaris Volume
Manager supports a maximum of four-way mirroring. When defining mirrors, first
create the mirror with the \fBmetainit\fR command as a one-way mirror. Then
attach subsequent submirrors using the \fBmetattach\fR command. This method
ensures that Solaris Volume Manager properly syncs the mirrors. (The second and
any subsequent submirrors are first created using the \fBmetainit\fR command.)
.RE

.sp
.ne 2
.na
\fB\fIread_options\fR\fR
.ad
.sp .6
.RS 4n
The following read options for mirrors are supported:
.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.sp .6
.RS 4n
Enables the geometric read option, which results in faster performance on
sequential reads.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.sp .6
.RS 4n
Directs all reads to the first submirror. This should only be used when the
devices comprising the first submirror are substantially faster than those of
the second mirror. This flag cannot be used with the \fB-g\fR flag.
.RE

If neither the \fB-g\fR nor \fB-r\fR flags are specified, reads are made in a
round-robin order from all submirrors in the mirror. This enables load
balancing across the submirrors.
.RE

.sp
.ne 2
.na
\fB\fIwrite_options\fR\fR
.ad
.sp .6
.RS 4n
The following write options for mirrors are supported:
.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.sp .6
.RS 4n
Performs serial writes to mirrors. The first submirror write completes before
the second is started. This can be useful if hardware is susceptible to partial
sector failures. If \fB-S\fR is not specified, writes are replicated and
dispatched to all mirrors simultaneously.
.RE

.RE

.sp
.ne 2
.na
\fB\fIpass_num\fR\fR
.ad
.sp .6
.RS 4n
A number in the range 0-9 at the end of an entry defining a mirror that
determines the order in which that mirror is resynced during a reboot. The
default is 1. Smaller pass numbers are resynced first. Equal pass numbers are
run concurrently. If 0 is used, the resync is skipped. 0 should be used only
for mirrors mounted as read-only, or as \fBswap\fR.
.RE

.SS "RAID Level 5 Options"
.sp
.LP
The following RAID level 5 options are available:
.sp
.ne 2
.na
\fB\fIRAID\fR \fB-r\fR\fR
.ad
.sp .6
.RS 4n
Specifies the name of the RAID level 5 metadevice. The \fB-r\fR specifies that
the configuration is RAID level 5.
.RE

.sp
.ne 2
.na
\fB\fB-k\fR\fR
.ad
.sp .6
.RS 4n
For RAID level 5 metadevices, informs the driver that it is not to initialize
(zero the disk blocks) due to existing data. Only use this option to recreate a
previously created RAID level 5 device.
.sp
Use the \fB-k\fR option with extreme caution. This option sets the disk blocks
to the \fBOK\fR state. If any errors exist on disk blocks within the
metadevice, Solaris Volume Manager might begin fabricating data. Instead of
using the \fB-k\fR option, you might want to initialize the device and restore
data from tape.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fB\fIoriginal_column_count\fR\fR\fR
.ad
.sp .6
.RS 4n
For RAID level 5 metadevices, used with the \fB-k\fR option to define the
number of original slices in the event the originally defined metadevice was
grown. This is necessary since the parity segments are not striped across
concatenated devices.
.sp
Use the \fB-o\fR option with extreme caution. This option sets the disk blocks
to the \fBOK\fR state. If any errors exist on disk blocks within the
metadevice, Solaris Volume Manager might begin fabricating data. Instead of
using the \fB-o\fR option, you might want to initialize the device and restore
data from tape.
.RE

.SS "Soft Partition Options"
.sp
.LP
The following soft partition options are supported:
.sp
.ne 2
.na
\fB\fIsoftpart\fR \fB-p\fR [\fB-e\fR] \fIcomponent\fR [\fB-A\fR
\fIalignment\fR] \fIsize\fR\fR
.ad
.sp .6
.RS 4n
The \fIsoftpart\fR argument specifies the name of the soft partition. The
\fB-p\fR specifies that the configuration is a soft partition.
.sp
The \fB-e\fR specifies that the entire disk specified by \fIcomponent\fR as
\fBc*t*d*\fR should be repartitioned and reserved for soft partitions. The
specified component is repartitioned such that slice 7 reserves space for
system (state database replica) usage and slice 0 contains all remaining space
on the disk. Slice 7 is a minimum of 4MB, but can be larger, depending on the
disk geometry. The newly created soft partition is placed on slice 0 of the
device.
.sp
The \fIcomponent\fR argument specifies the disk (\fBc*t*d*\fR), slice
(\fBc*t*d*s*\fR), or meta device (\fBd*\fR) from which to create the soft
partition. The \fIsize\fR argument determines the space to use for the soft
partition and can be specified in \fBK\fR or \fBk\fR for kilobytes, \fBM\fR or
\fBm\fR for megabytes, \fBG\fR or \fBg\fR for gigabytes, \fBT\fR or \fBt\fR for
terabyte (one terabyte is the maximum size), and \fBB\fR or \fBb\fR for blocks
(sectors). All values represent powers of 2, and upper and lower case options
are equivalent. Only integer values are permitted.
.sp
The \fB-A\fR alignment option sets the value of the soft partition extent
alignment. This option used when it is important specify a starting offset for
the soft partition. It preserves the data alignment between the metadevice
address space and the address space of the underlying physical device. For
example, a hardware device that does checksumming should not have its I/O
requests divided by Solaris Volume Manager. In this case, use a value from the
hardware configuration as the value for the alignment. When you use this option
in conjunction with a software I/O load, the alignment value corresponds to the
I/O load of the application. This prevents I/O from being divided unnecessarily
and affecting performance.
.sp
The literal \fBall\fR, used instead of specifying size, specifies that the soft
partition should occupy all available space on the device.
.RE

.SS "Hot Spare Pool Options"
.sp
.LP
The following hot spare pool options are supported:
.sp
.ne 2
.na
\fB\fIhot_spare_pool\fR \fI\fR\fB[\fR\fI\fR \fI\fR\fIhotspare...\fR\fI\fR
\fI\fR\fB]\fR\fI\fR\fR
.ad
.sp .6
.RS 4n
When used as arguments to the \fBmetainit\fR command, \fIhot_spare_pool\fR
defines the name for a hot spare pool, and \fIhotspare...\fR is the logical
name for the physical slice(s) for availability in that pool. Names for hot
spare pools can be any legal file name that is composed of alphanumeric
characters, a dash ("-"), an underscore ("_"), or a period ("."). Names must
begin with a letter. The words "all" and "none" are reserved and cannot be
used.
.RE

.SS "\fBmd.tab\fR File Options"
.sp
.LP
The following \fBmd.tab\fR file options are supported:
.sp
.ne 2
.na
\fB\fImetadevice-name\fR\fR
.ad
.sp .6
.RS 4n
When the \fBmetainit\fR command is run with a \fImetadevice-name\fR as its only
argument, it searches the \fB/etc/lvm/md.tab\fR file to find that name and its
corresponding entry. The order in which entries appear in the \fBmd.tab\fR file
is unimportant. For example, consider the following \fBmd.tab\fR entry:
.sp
.in +2
.nf
d0 2 1 c1t0d0s0 1 c2t1d0s0
.fi
.in -2
.sp

When you run the command \fBmetainit d0\fR, it configures metadevice \fBd0\fR
based on the configuration information found in the \fBmd.tab\fR file.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.sp .6
.RS 4n
Activates all metadevices defined in the \fBmd.tab\fR file.
.sp
\fBmetainit\fR does not maintain the state of the volumes that would have been
created when \fBmetainit\fR is run with both the \fB-a\fR and \fB-n\fR flags.
If a device \fBd0\fR is created in the first line of the \fBmd.tab\fR file, and
a later line in \fBmd.tab\fR assumes the existence of \fBd0\fR, the later line
fails when \fBmetainit\fR \fB-an\fR runs (even if it would succeed with
\fBmetainit\fR \fB-a\fR).
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a One-on-One Concatenation
.sp
.LP
The following command creates a one-on-one concatenation for the root slice.
This is the first step you take when setting up a mirror for the root slice
(and any other slice that cannot be unmounted). The \fB-f\fR option is required
to create a volume with an existing file system, such as root(\fB/\fR).

.sp
.in +2
.nf
# metainit \fB-f\fR dl 1 1 c0t0d0s0
.fi
.in -2
.sp

.sp
.LP
The preceding command makes \fBd1\fR a one-on-one concatenation, using the root
slice. You can then enter:

.sp
.in +2
.nf
# metainit d0 -m d1
.fi
.in -2
.sp

.sp
.LP
\&...to make a one-way mirror of the root slice.

.LP
\fBExample 2 \fRConcatenation
.sp
.LP
All drives in the following examples have the same size of 525 Mbytes.

.sp
.LP
This example shows a metadevice, \fB/dev/md/dsk/d7\fR, consisting of a
concatenation of four slices.

.sp
.in +2
.nf
# metainit d7 4 1 c0t1d0s0 1 c0t2d0s0 1 c0t3d0s0 1 /dev/dsk/c0t4d0s0
.fi
.in -2
.sp

.sp
.LP
The number 4 indicates there are four individual stripes in the concatenation.
Each stripe is made of one slice, hence the number 1 appears in front of each
slice. The first disk sector in all of these devices contains a disk label. To
preserve the labels on devices \fB/dev/dsk/c0t2d0s0\fR,
\fB/dev/dsk/c0t3d0s0\fR, and \fB/dev/dsk/c0t4d0s0\fR, the metadisk driver must
skip at least the first sector of those disks when mapping accesses across the
concatenation boundaries. Because skipping only the first sector would create
an irregular disk geometry, the entire first cylinder of these disks is
skipped. This allows higher level file system software to optimize block
allocations correctly.

.LP
\fBExample 3 \fRStripe
.sp
.LP
This example shows a metadevice, \fB/dev/md/dsk/d15\fR, consisting of two
slices.

.sp
.in +2
.nf
# metainit d15 1 2 c0t1d0s0 c0t2d0s0 -i 32k
.fi
.in -2
.sp

.sp
.LP
The number 1 indicates that one stripe is being created. Because the stripe is
made of two slices, the number 2 follows next. The optional \fB-i\fR followed
by \fB32k\fR specifies the interlace size as 32 Kbytes. If the interlace size
were not specified, the stripe would use the default value of 16 Kbytes.

.LP
\fBExample 4 \fRConcatentation of Stripes
.sp
.LP
This example shows a metadevice, \fB/dev/md/dsk/d75\fR, consisting of a
concatenation of two stripes of three disks.

.sp
.in +2
.nf
# metainit d75 2 3 c0t1d0s0 c0t2d0s0 \e
      c0t3d0s0 -i 16k \e
      3 c1t1d0s0 c1t2d0s0 c1t3d0s0 -i 32k
.fi
.in -2
.sp

.sp
.LP
On the first line, the \fB-i\fR followed by 16k specifies that the stripe
interlace size is 16 Kbytes. The second set specifies the stripe interlace size
as 32 Kbytes. If the second set did not specify 32 Kbytes, the set would use
the default interlace value of 16 Kbytes. The blocks of each set of three disks
are interlaced across three disks.

.LP
\fBExample 5 \fRMirroring
.sp
.LP
This example shows a two-way mirror, \fB/dev/md/dsk/d50\fR, consisting of two
submirrors. This mirror does not contain any existing data.

.sp
.in +2
.nf
# metainit d51 1 1 c0t1d0s0
# metainit d52 1 1 c0t2d0s0
# metainit d50 -m d51
# metattach d50 d52
.fi
.in -2
.sp

.sp
.LP
In this example, two submirrors, \fBd51\fR and \fBd52\fR, are created with the
\fBmetainit\fR command. These two submirrors are simple concatenations. Next, a
one-way mirror, \fBd50\fR, is created using the \fB-m\fR option with \fBd51\fR.
The second submirror is attached later using the \fBmetattach\fR command. When
creating a mirror, any combination of stripes and concatenations can be used.
The default read and write options in this example are a round-robin read
algorithm and parallel writes to all submirrors.

.LP
\fBExample 6 \fRCreating a metadevice in a diskset
.sp
.LP
This example shows a metadevice, \fB/dev/md/dsk/d75\fR, consisting of a
concatenation of two stripes within a diskset called \fBset1\fR.

.sp
.in +2
.nf
# metainit -s set1 d75 2 3 c2t1d0s0 c2t2d0s0 \e
      c2t3d0s0 -i 32k
# metainit -s set1 d51 1 1 c2t1d0s0
# metainit -s set1 d52 1 1 c3t1d0s0
# metainit -s set1 d50 -m d51
# metattach -s set1 d50 d52
.fi
.in -2
.sp

.sp
.LP
In this example, a diskset is created using the \fBmetaset\fR command.
Metadevices are then created within the diskset using the \fBmetainit\fR
command. The two submirrors, \fBd51\fR and \fBd52\fR, are simple
concatenations. Next, a one-way mirror, \fBd50\fR, is created using the
\fB-m\fR option with \fBd51\fR. The second submirror is attached later using
the \fBmetattach\fR command. When creating a mirror, any combination of stripes
and concatenations can be used. The default read and write options in this
example are a round-robin read algorithm and parallel writes to all submirrors.

.LP
\fBExample 7 \fRRAID Level 5
.sp
.LP
This example shows a RAID level 5 device, \fBd80\fR, consisting of three
slices:

.sp
.in +2
.nf
# metainit d80 -r c1t0d0s0 c1t1d0s0 c1t3d0s0 -i 20k
.fi
.in -2
.sp

.sp
.LP
In this example, a RAID level 5 metadevice is defined using the \fB-r\fR option
with an interlace size of 20 Kbytes. The data and parity segments are striped
across the slices, \fBc1t0d0s0\fR, \fBc1t2d0s0\fR, and \fBc1t3d0s0\fR.

.LP
\fBExample 8 \fRSoft Partition
.sp
.LP
The following example shows a soft partition device, \fBd1\fR, built on
metadevice \fBd100\fR and 100 Mbytes (indicated by \fB100M\fR) in size:

.sp
.in +2
.nf
# metainit d1 -p d100 100M
.fi
.in -2
.sp

.sp
.LP
The preceding command creates a 100 Mbyte soft partition on the \fBd100\fR
metadevice. This metadevice could be a RAID level 5, stripe, concatenation, or
mirror.

.LP
\fBExample 9 \fRSoft Partition on Full Disk
.sp
.LP
The following example shows a soft partition device, \fBd1\fR, built on disk
\fBc3t4d0\fR:

.sp
.in +2
.nf
# metainit d1 -p -e c3t4d0 9G
.fi
.in -2
.sp

.sp
.LP
In this example, the disk is repartitioned and a soft partition is defined to
occupy all 9 Gbytes of disk \fBc3t4d0s0\fR.

.LP
\fBExample 10 \fRSoft Partition Taking All Available Space
.sp
.LP
The following example shows a soft partition device, \fBd1\fR, built on disk
\fBc3t4d0\fR:

.sp
.in +2
.nf
# metainit d1 -p -e c3t4d0 all
.fi
.in -2
.sp

.sp
.LP
In this example, the disk is repartitioned and a soft partition is defined to
occupy all available disk space on slice \fBc3t4d0s0\fR.

.LP
\fBExample 11 \fRHot Spare
.sp
.LP
This example shows a two-way mirror, \fB/dev/md/dsk/d10\fR, and a hot spare
pool with three hot spare components. The mirror does not contain any existing
data.

.sp
.in +2
.nf
# metainit hsp001 c2t2d0s0 c3t2d0s0 c1t2d0s0
# metainit d41 1 1 c1t0d0s0 -h hsp001
# metainit d42 1 1 c3t0d0s0 -h hsp001
# metainit d40 -m d41
# metattach d40 d42
.fi
.in -2
.sp

.sp
.LP
In this example, a hot spare pool, \fBhsp001\fR, is created with three slices
from three different disks used as hot spares. Next, two submirrors are
created, \fBd41\fR and \fBd42\fR. These are simple concatenations. The
\fBmetainit\fR command uses the \fB-h\fR option to associate the hot spare pool
\fBhsp001\fR with each submirror. A one-way mirror is then defined using the
\fB-m\fR option. The second submirror is attached using the \fBmetattach\fR
command.

.LP
\fBExample 12 \fRSetting the Value of the Soft Partition Extent Alignment
.sp
.LP
This example shows how to set the alignment of the soft partition to 1
megabyte.

.sp
.in +2
.nf
# metainit -s red d13 -p c1t3d0s4 -A 1m 4m
.fi
.in -2
.sp

.sp
.LP
In this example the soft partition, \fBd13\fR, is created with an extent
alignment of 1 megabyte. The \fBmetainit\fR command uses the \fB-A\fR option
with an alignment of \fB1m\fR to define the soft partition extent alignment.

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/lvm/md.tab\fR\fR
.ad
.sp .6
.RS 4n
Contains list of metadevice and hot spare configurations for batch-like
creation.
.RE

.SH WARNINGS
.sp
.LP
This section contains information on different types of warnings.
.SS "Devices and Volumes Greater Than 1 TB"
.sp
.LP
Do not create large (>1 TB) volumes if you expect to run the Solaris Operating
Environment with a 32-bit kernel or if you expect to use a version of the
Solaris Operating Environment prior to Solaris 10.
.SS "Multi-Way Mirror"
.sp
.LP
Do not use the \fBmetainit\fR command to create a multi-way mirror. Rather,
create a one-way mirror with \fBmetainit\fR then attach additional submirrors
with \fBmetattach\fR. When the \fBmetattach\fR command is not used, no resync
operations occur and data could become corrupted.
.sp
.LP
If you use \fBmetainit\fR to create a mirror with multiple submirrors, the
following message is displayed:
.sp
.in +2
.nf
WARNING: This form of metainit is not recommended.
The submirrors may not have the same data.
Please see ERRORS in metainit(1M) for additional information.
.fi
.in -2
.sp

.SS "Truncation of Soft Partitions"
.sp
.LP
When creating stripes on top of soft partitions it is possible for the size of
the new stripe to be less than the size of the underlying soft partition. If
this occurs, \fBmetainit\fR fails with an error indicating the actions required
to overcome the failure.
.sp
.LP
If you use the \fB-f\fR option to override this behavior, the following message
is displayed:
.sp
.in +2
.nf
WARNING: This form of metainit is not recommended.
The stripe is truncating the size of the underlying device.
Please see ERRORS in metainit(1M) for additional information.
.fi
.in -2
.sp

.SS "Write-On-Write Problem"
.sp
.LP
When mirroring data in Solaris Volume Manager, transfers from memory to the
disks do not all occur at exactly the same time for all sides of the mirror. If
the contents of buffers are changed while the data is in-flight to the disk
(called write-on-write), then different data can end up being stored on each
side of a mirror.
.sp
.LP
This problem can be addressed by making a private copy of the data for mirror
writes, however, doing this copy is expensive. Another approach is to detect
when memory has been modified across a write by looking at the dirty-bit
associated with the memory page. Solaris Volume Manager uses this dirty-bit
technique when it can. Unfortunately, this technique does not work for raw I/O
or direct I/O. By default, Solaris Volume Manager is tuned for performance with
the liability that mirrored data might be out of sync if an application does a
"write-on-write" to buffers associated with raw I/O or direct I/O. Without
mirroring, you were not guaranteed what data would actually end up on media,
but multiple reads would return the same data. With mirroring, multiple reads
can return different data. The following line can be added to \fB/etc/system\fR
to cause a stable copy of the buffers to be used for all raw I/O and direct I/O
write operations.
.sp
.in +2
.nf
set md_mirror:md_mirror_wow_flg=0x20
.fi
.in -2
.sp

.sp
.LP
Setting this flag degrades performance.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.sp .6
.RS 4n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.sp .6
.RS 4n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     Stable
.TE

.SH SEE ALSO
.sp
.LP
\fBmdmonitord\fR(1M), \fBmetaclear\fR(1M), \fBmetadb\fR(1M),
\fBmetadetach\fR(1M), \fBmetahs\fR(1M), \fBmetaoffline\fR(1M),
\fBmetaonline\fR(1M), \fBmetaparam\fR(1M), \fBmetarecover\fR(1M),
\fBmetarename\fR(1M), \fBmetareplace\fR(1M), \fBmetaroot\fR(1M),
\fBmetaset\fR(1M), \fBmetassist\fR(1M), \fBmetastat\fR(1M), \fBmetasync\fR(1M),
\fBmetattach\fR(1M), \fBmd.tab\fR(4), \fBmd.cf\fR(4), \fBmddb.cf\fR(4),
\fBmd.tab\fR(4), \fBattributes\fR(5), \fBmd\fR(7D)
.sp
.LP
\fI\fR
.SH LIMITATIONS
.sp
.LP
Recursive mirroring is not allowed; that is, a mirror cannot appear in the
definition of another mirror.
.sp
.LP
Recursive logging is not allowed; that is, a trans metadevice cannot appear in
the definition of another metadevice.
.sp
.LP
Stripes, concatenations, and RAID level 5 metadevices must consist of slices
only.
.sp
.LP
Mirroring of RAID level 5 metadevices is not allowed.
.sp
.LP
Soft partitions can be built on raw devices, or on stripes, RAID level 5, or
mirrors.
.sp
.LP
RAID level 5 or stripe metadevices can be built directly on soft partitions.
.SH NOTES
.sp
.LP
Trans metadevices have been replaced by UFS logging. Existing trans devices are
\fBnot\fR logging--they pass data directly through to the underlying device.
See \fBmount_ufs\fR(1M) for more information about UFS logging.