Print this page 
blah
2897 "zpool split" documentation missing from manpage
Reviewed by: Dan McDonald <danmcd@omniti.com>
Split Close
Expand all
Collapse all
          --- old/usr/src/man/man1m/zpool.1m
          +++ new/usr/src/man/man1m/zpool.1m
↓ open down ↓ 130 lines elided ↑ open up ↑ 
 131  131  \fBzpool scrub\fR [\fB-s\fR] \fIpool\fR ...
 132  132  .fi
 133  133  
 134  134  .LP
 135  135  .nf
 136  136  \fBzpool set\fR \fIproperty\fR=\fIvalue\fR \fIpool\fR
 137  137  .fi
 138  138  
 139  139  .LP
 140  140  .nf
      141 +\fBzpool split\fR [\fB-n\fR] [\fB-R\fR \fIaltroot\fR] [\fB-o\fR \fImntopts\fR] [\fB-o\fR \fIproperty=value\fR] \fIpool\fR \fInewpool\fR [\fIdevice\fR ... ]
      142 +.fi
      143 +
      144 +.LP
      145 +.nf
 141  146  \fBzpool status\fR [\fB-xvD\fR] [\fB-T\fR \fBu\fR | \fBd\fR ] [\fIpool\fR] ... [\fIinterval\fR [\fIcount\fR]]
 142  147  .fi
 143  148  
 144  149  .LP
 145  150  .nf
 146  151  \fBzpool upgrade\fR
 147  152  .fi
 148  153  
 149  154  .LP
 150  155  .nf
 151  156  \fBzpool upgrade\fR \fB-v\fR
 152  157  .fi
 153  158  
 154  159  .LP
 155  160  .nf
 156  161  \fBzpool upgrade\fR [\fB-V\fR \fIversion\fR] \fB-a\fR | \fIpool\fR ...
 157  162  .fi
 158  163  
 159  164  .SH DESCRIPTION
 160      -.sp
 161  165  .LP
 162  166  The \fBzpool\fR command configures \fBZFS\fR storage pools. A storage pool is a
 163  167  collection of devices that provides physical storage and data replication for
 164  168  \fBZFS\fR datasets.
 165  169  .sp
 166  170  .LP
 167  171  All datasets within a storage pool share the same space. See \fBzfs\fR(1M) for
 168  172  information on managing datasets.
 169  173  .SS "Virtual Devices (\fBvdev\fRs)"
 170      -.sp
 171  174  .LP
 172  175  A "virtual device" describes a single device or a collection of devices
 173  176  organized according to certain performance and fault characteristics. The
 174  177  following virtual devices are supported:
 175  178  .sp
 176  179  .ne 2
 177  180  .na
 178  181  \fB\fBdisk\fR\fR
 179  182  .ad
 180  183  .RS 10n
↓ open down ↓ 120 lines elided ↑ open up ↑ 
 301  304  vdevs, each a mirror of two disks:
 302  305  .sp
 303  306  .in +2
 304  307  .nf
 305  308  # \fBzpool create mypool mirror c0t0d0 c0t1d0 mirror c1t0d0 c1t1d0\fR
 306  309  .fi
 307  310  .in -2
 308  311  .sp
 309  312  
 310  313  .SS "Device Failure and Recovery"
 311      -.sp
 312  314  .LP
 313  315  \fBZFS\fR supports a rich set of mechanisms for handling device failure and
 314  316  data corruption. All metadata and data is checksummed, and \fBZFS\fR
 315  317  automatically repairs bad data from a good copy when corruption is detected.
 316  318  .sp
 317  319  .LP
 318  320  In order to take advantage of these features, a pool must make use of some form
 319  321  of redundancy, using either mirrored or \fBraidz\fR groups. While \fBZFS\fR
 320  322  supports running in a non-redundant configuration, where each root vdev is
 321  323  simply a disk or file, this is strongly discouraged. A single case of bit
↓ open down ↓ 109 lines elided ↑ open up ↑ 
 431  433  unavailable, then the device will be identified by a unique identifier instead
 432  434  of its path since the path was never correct in the first place.
 433  435  .RE
 434  436  
 435  437  .sp
 436  438  .LP
 437  439  If a device is removed and later re-attached to the system, \fBZFS\fR attempts
 438  440  to put the device online automatically. Device attach detection is
 439  441  hardware-dependent and might not be supported on all platforms.
 440  442  .SS "Hot Spares"
 441      -.sp
 442  443  .LP
 443  444  \fBZFS\fR allows devices to be associated with pools as "hot spares". These
 444  445  devices are not actively used in the pool, but when an active device fails, it
 445  446  is automatically replaced by a hot spare. To create a pool with hot spares,
 446  447  specify a "spare" \fBvdev\fR with any number of devices. For example,
 447  448  .sp
 448  449  .in +2
 449  450  .nf
 450  451  # zpool create pool mirror c0d0 c1d0 spare c2d0 c3d0
 451  452  .fi
↓ open down ↓ 15 lines elided ↑ open up ↑ 
 467  468  .sp
 468  469  .LP
 469  470  An in-progress spare replacement can be cancelled by detaching the hot spare.
 470  471  If the original faulted device is detached, then the hot spare assumes its
 471  472  place in the configuration, and is removed from the spare list of all active
 472  473  pools.
 473  474  .sp
 474  475  .LP
 475  476  Spares cannot replace log devices.
 476  477  .SS "Intent Log"
 477      -.sp
 478  478  .LP
 479  479  The \fBZFS\fR Intent Log (\fBZIL\fR) satisfies \fBPOSIX\fR requirements for
 480  480  synchronous transactions. For instance, databases often require their
 481  481  transactions to be on stable storage devices when returning from a system call.
 482  482  \fBNFS\fR and other applications can also use \fBfsync\fR() to ensure data
 483  483  stability. By default, the intent log is allocated from blocks within the main
 484  484  pool. However, it might be possible to get better performance using separate
 485  485  intent log devices such as \fBNVRAM\fR or a dedicated disk. For example:
 486  486  .sp
 487  487  .in +2
↓ open down ↓ 6 lines elided ↑ open up ↑ 
 494  494  .sp
 495  495  .LP
 496  496  Multiple log devices can also be specified, and they can be mirrored. See the
 497  497  EXAMPLES section for an example of mirroring multiple log devices.
 498  498  .sp
 499  499  .LP
 500  500  Log devices can be added, replaced, attached, detached, and imported and
 501  501  exported as part of the larger pool. Mirrored log devices can be removed by
 502  502  specifying the top-level mirror for the log.
 503  503  .SS "Cache Devices"
 504      -.sp
 505  504  .LP
 506  505  Devices can be added to a storage pool as "cache devices." These devices
 507  506  provide an additional layer of caching between main memory and disk. For
 508  507  read-heavy workloads, where the working set size is much larger than what can
 509  508  be cached in main memory, using cache devices allow much more of this working
 510  509  set to be served from low latency media. Using cache devices provides the
 511  510  greatest performance improvement for random read-workloads of mostly static
 512  511  content.
 513  512  .sp
 514  513  .LP
↓ open down ↓ 11 lines elided ↑ open up ↑ 
 526  525  .LP
 527  526  Cache devices cannot be mirrored or part of a \fBraidz\fR configuration. If a
 528  527  read error is encountered on a cache device, that read \fBI/O\fR is reissued to
 529  528  the original storage pool device, which might be part of a mirrored or
 530  529  \fBraidz\fR configuration.
 531  530  .sp
 532  531  .LP
 533  532  The content of the cache devices is considered volatile, as is the case with
 534  533  other system caches.
 535  534  .SS "Properties"
 536      -.sp
 537  535  .LP
 538  536  Each pool has several properties associated with it. Some properties are
 539  537  read-only statistics while others are configurable and change the behavior of
 540  538  the pool. The following are read-only properties:
 541  539  .sp
 542  540  .ne 2
 543  541  .na
 544  542  \fB\fBavailable\fR\fR
 545  543  .ad
 546  544  .RS 20n
↓ open down ↓ 323 lines elided ↑ open up ↑ 
 870  868  .sp .6
 871  869  .RS 4n
 872  870  The current on-disk version of the pool. This can be increased, but never
 873  871  decreased. The preferred method of updating pools is with the "\fBzpool
 874  872  upgrade\fR" command, though this property can be used when a specific version
 875  873  is needed for backwards compatibility. Once feature flags is enabled on a
 876  874  pool this property will no longer have a value.
 877  875  .RE
 878  876  
 879  877  .SS "Subcommands"
 880      -.sp
 881  878  .LP
 882  879  All subcommands that modify state are logged persistently to the pool in their
 883  880  original form.
 884  881  .sp
 885  882  .LP
 886  883  The \fBzpool\fR command provides subcommands to create and destroy storage
 887  884  pools, add capacity to storage pools, and provide information about the storage
 888  885  pools. The following subcommands are supported:
 889  886  .sp
 890  887  .ne 2
↓ open down ↓ 937 lines elided ↑ open up ↑ 
1828 1825  .ad
1829 1826  .sp .6
1830 1827  .RS 4n
1831 1828  Sets the given property on the specified pool. See the "Properties" section for
1832 1829  more information on what properties can be set and acceptable values.
1833 1830  .RE
1834 1831  
1835 1832  .sp
1836 1833  .ne 2
1837 1834  .na
     1835 +\fBzpool split\fR [\fB-n\fR] [\fB-R\fR \fIaltroot\fR] [\fB-o\fR \fImntopts\fR] [\fB-o\fR \fIproperty=value\fR] \fIpool\fR \fInewpool\fR [\fIdevice\fR ... ]
     1836 +.ad
     1837 +.sp .6
     1838 +.RS 4n
     1839 +
     1840 +Splits off one disk from each mirrored top-level vdev in a pool and creates a
     1841 +new pool from the split-off disks. The original pool must be made up of one
     1842 +or more mirrors and must not be in the process of resilvering. The \fBsplit\fR
     1843 +subcommand chooses the last device in each mirror vdev unless overridden by a
     1844 +device specification on the command line.
     1845 +
     1846 +When using a \fIdevice\fR argument, \fBsplit\fR includes the specified
     1847 +device(s) in a new pool and, should any devices remain unspecified, assigns
     1848 +the last device in each mirror vdev to that pool, as it does normally. If you
     1849 +are uncertain about the outcome of a \fBsplit\fR command, use the \fI-n\fR
     1850 +("dry-run") option to ensure your command will have the effect you intend.
     1851 +
     1852 +.sp
     1853 +.ne 2
     1854 +.na
     1855 +\fB\fB-n\fR \fR
     1856 +.ad
     1857 +.sp .6
     1858 +.RS 4n
     1859 +Displays the configuration that would be created without actually splitting
     1860 +the pool. The actual pool split could still fail due to insufficient
     1861 +privileges or device status.
     1862 +.RE
     1863 +
     1864 +.sp
     1865 +.ne 2
     1866 +.na
     1867 +\fB\fB-R\fR \fIaltroot\fR \fR
     1868 +.ad
     1869 +.sp .6
     1870 +.RS 4n
     1871 +Automatically import the newly created pool after splitting, using the
     1872 +specified \fIaltroot\fR parameter for the new pool's alternate root. See the
     1873 +\fBaltroot\fR description in the "Properties" section, above.
     1874 +.RE
     1875 +
     1876 +.sp
     1877 +.ne 2
     1878 +.na
     1879 +\fB\fB-o\fR \fImntopts\fR \fR
     1880 +.ad
     1881 +.sp .6
     1882 +.RS 4n
     1883 +Comma-separated list of mount options to use when mounting datasets within
     1884 +the pool. See \fBzfs\fR(1M) for a description of dataset properties and mount
     1885 +options. Valid only in conjunction with the \fB-R\fR option.
     1886 +.RE
     1887 +
     1888 +.sp
     1889 +.ne 2
     1890 +.na
     1891 +\fB\fB-o\fR \fIproperty=value\fR \fR
     1892 +.ad
     1893 +.sp .6
     1894 +.RS 4n
     1895 +Sets the specified property on the new pool. See the "Properties" section,
     1896 +above, for more information on the available pool properties.
     1897 +.RE
     1898 +
     1899 +.RE
     1900 +
     1901 +.sp
     1902 +.ne 2
     1903 +.na
1838 1904  \fBzpool status\fR [\fB-xvD\fR] [\fB-T\fR \fBu\fR | \fBd\fR ] [\fIpool\fR] ... [\fIinterval\fR [\fIcount\fR]]
1839 1905  .ad
1840 1906  .sp .6
1841 1907  .RS 4n
1842 1908  Displays the detailed health status for the given pools. If no \fIpool\fR is
1843 1909  specified, then the status of each pool in the system is displayed. For more
1844 1910  information on pool and device health, see the "Device Failure and Recovery"
1845 1911  section.
1846 1912  .sp
1847 1913  If a scrub or resilver is in progress, this command reports the percentage done
↓ open down ↓ 431 lines elided ↑ open up ↑ 
2279 2345  NAME         SIZE  ALLOC   FREE   FRAG  EXPANDSZ    CAP  DEDUP  HEALTH  ALTROOT
2280 2346  data        23.9G  14.6G  9.30G    48%         -    61%  1.00x  ONLINE  -
2281 2347    raidz1    23.9G  14.6G  9.30G    48%         -
2282 2348      c1t1d0      -      -      -      -         -
2283 2349      c1t2d0      -      -      -      -       10G
2284 2350      c1t3d0      -      -      -      -         -
2285 2351  .fi
2286 2352  .in -2
2287 2353  
2288 2354  .SH EXIT STATUS
2289      -.sp
2290 2355  .LP
2291 2356  The following exit values are returned:
2292 2357  .sp
2293 2358  .ne 2
2294 2359  .na
2295 2360  \fB\fB0\fR\fR
2296 2361  .ad
2297 2362  .RS 5n
2298 2363  Successful completion.
2299 2364  .RE
↓ open down ↓ 10 lines elided ↑ open up ↑ 
2310 2375  .sp
2311 2376  .ne 2
2312 2377  .na
2313 2378  \fB\fB2\fR\fR
2314 2379  .ad
2315 2380  .RS 5n
2316 2381  Invalid command line options were specified.
2317 2382  .RE
2318 2383  
2319 2384  .SH ATTRIBUTES
2320      -.sp
2321 2385  .LP
2322 2386  See \fBattributes\fR(5) for descriptions of the following attributes:
2323 2387  .sp
2324 2388  
2325 2389  .sp
2326 2390  .TS
2327 2391  box;
2328 2392  c | c
2329 2393  l | l .
2330 2394  ATTRIBUTE TYPE  ATTRIBUTE VALUE
2331 2395  _
2332 2396  Interface Stability     Evolving
2333 2397  .TE
2334 2398  
2335 2399  .SH SEE ALSO
2336      -.sp
2337 2400  .LP
2338 2401  \fBzfs\fR(1M), \fBzpool-features\fR(5), \fBattributes\fR(5)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX