4.4.1 Creating a Pool

To create a storage pool, use the zpool create command. The command takes a pool name and any number of virtual devices. The pool name must satisfy the naming conventions outlined in 1.3 ZFS Component Naming Conventions.

4.4.1.1 Basic Pool

The following command creates a new pool named tank consisting of the disks c0t0d0 and c1t0d0:

# zpool create tank c0t0d0 c1t0d0

As described in the previous section, these whole disks are found under the /dev/dsk directory and labelled appropriately to contain a single, large slice. Data is dynamically striped across both disks.

4.4.1.2 Mirrored Pool

To create a mirrored pool, use the mirror keyword, followed by any number of storage devices comprising the mirror. Multiple mirrors can be specified by repeating the mirror keyword on the command line. The following command creates a pool with two, two-way mirrors:

# zpool create tank mirror c0d0 c1d0 mirror c0d1 c1d1

The second mirror keyword indicates that a new top-level virtual device is being specified. Data is dynamically striped across both mirrors, with data being replicated between each disk appropriately.

4.4.1.3 RAID-Z Pool

Creating a RAID-Z pool is identical to a mirrored pool, except that the raidz keyword is used instead of mirror. The following command creates a pool with a single RAID-Z device consisting of 5 disk slices:

# zpool create tank raidz c0t0d0s0 c0t0d1s0 c0t0d2s0 c0t0d3s0 
/dev/dsk/c0t0d4s0

In the above example, the disk must have been pre-formatted to have an appropriately sized slice zero. The above command also demonstrates that disks can be specified using their full path. /dev/dsk/c0t0d4s0 is identical to c0t0d4s0 by itself.

Note that there is no requirement to use disk slices in a RAID-Z configuration. The above command is just an example of using disk slices in a storage pool.

4.4.2 Handling Pool Creation Errors

There are a number of reasons that a pool cannot be created. Some of these are obvious, such as when a specified device doesn't exist, while others are more subtle.

4.4.2.1 Detecting In-Use Devices

Before formatting a device, ZFS first checks to see if it is in use by ZFS or some other part of the operating system. If this is the case, you may see errors such as:

# zpool create tank c0t0d0 c1t0d0
invalid vdev specification
use '-f' to override the following errors:
/dev/dsk/c0t0d0s0 is currently mounted on /
/dev/dsk/c0t0d0s1 is currently mounted on swap
/dev/dsk/c1t1d0s0 is part of active pool 'tank'

Some of these errors can be overridden by using the -f flag, but most cannot. The following uses cannot be overridden using -f, and must be manually corrected by the administrator:

The following in-use checks serve as helpful warnings, and can be overridden using the -f flag to create:

The following example demonstrates how the -f flag is used:

# zpool create tank c0t0d0
invalid vdev specification
use '-f' to override the following errors:
/dev/dsk/c0t0d0s0 contains a ufs filesystem
# zpool create -f tank c0t0d0

It is recommended that you correct the errors rather than using the -f flag.

4.4.2.2 Mismatched Replication Levels

Creating pools with virtual devices of different replication levels is not recommended. The zpool(1M) command tries to prevent you from accidentally creating a pool with mismatched replication levels. If you try to create a pool with such a configuration, you will see errors similar to the following:

# zpool create tank c0t0d0 mirror c0t0d1 c0t0d2
invalid vdev specification: mirror requires at least 2 devices
# zpool create tank mirror c0t0d0 c0t0d1 mirror c1t0d0 c1t0d1 c1t0d2
use '-f' to override the following errors:
mismatched replication level: 2-way mirror and 3-way mirror vdevs are present

These errors can be overridden with the -f flag, though doing so is not recommended. The command also warns about creating a mirrored or RAID-Z pool using devices of different sizes. While this is allowed, it results in unused space on the larger device, and requires the -f flag to override the warning.

4.4.2.3 Doing a Dry Run

Because there are so many ways that creation can fail unexpectedly, and because formatting disks is such a potentially harmful action, the zfs create command has an additional option, -n, which simulates creating the pool without actually writing data to disk. This option does the device in-use checking and replication level validation, and reports any errors in the process. If no errors are found, you see output similar to the following

# zpool create -n tank mirror c1t0d0 c1t1d1
would create 'tank' with the following layout:

        tank
          mirror
            c1t0d0
            c1t1d0

There are some errors that cannot be detected without actually creating the pool. The most common example is specifying the same device twice in the same configuration. This cannot be reliably detected without writing the data itself, so it is possible for create -n to report success and yet fail to create the pool when run for real.

4.4.2.4 Default Mount Point for Pools

When a pool is created, the default mount point for the root dataset is /poolname by default. This directory must either not exist (in which case it is automatically created) or empty (in which case the root dataset is mounted on top of the existing directory). To create a pool with a different default mount point, use zpool create's -m option:

# zpool create home c0t0d0
default mountpoint '/home' exists and is not empty
use '-m' option to specify a different default
# zpool create -m /export/zfs home c0t0d0

This command creates a new pool home with the home dataset having a mount point of /export/zfs.

For more information on mount points, see 5.5.1 Managing Mount Points.

4.4.3 Destroying Pools

Pools are destroyed by using the zpool destroy command. This command destroys the pool even if it contains mounted datasets.

# zpool destroy tank

Caution - Currently, once a pool is destroyed, your data is gone. Be very careful when you destroy a pool.

4.4.3.1 Destroying a Pool With Faulted Devices

The act of destroying a pool requires that data be written to disk to indicate that the pool is no longer valid. This prevents the devices from showing up as a potential pool when doing an import. If one or more devices is unavailable, the pool can still be destroyed but the necessary state won't be written to these damaged devices. This means that these devices, when suitably repaired, are reported as 'potentially active' when creating new pools, and appear as valid devices when searching for pools to import. If a pool has enough faulted devices such that the pool itself is faulted (a top-level virtual device is faulted), then the command prints a warning and refuses to complete without the -f flag. This is because we cannot open the pool, so we don't know if there is any data stored or not. For example:

# zpool destroy tank
cannot destroy 'tank': pool is faulted
use '-f' to force destruction anyway
# zpool destroy -f tank

For more information on pool and device health, see 4.6.3 Health Status.

For more information on importing pools, see 4.7.5 Importing Pools.