diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/content/en/books/handbook/zfs/_index.adoc --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/content/en/books/handbook/zfs/_index.adoc @@ -98,29 +98,29 @@ # service zfs start .... -The examples in this section assume three SCSI disks with the device names [.filename]#da0#, [.filename]#da1#, and [.filename]#da2#. -Users of SATA hardware should instead use [.filename]#ada# device names. +The examples in this section assume three SATA disks with the device names [.filename]#ada0#, [.filename]#ada1#, and [.filename]#ada2#. +Users of SCSI/SAS hardware should instead use [.filename]#da# device names. [[zfs-quickstart-single-disk-pool]] === Single Disk Pool -To create a simple, non-redundant pool using a single disk device: +Create a GPT partition on an empty disk first. +Then add a partition of type `freebsd-zfs` from which a single, non-redundant pool is created: [source,shell] .... -# zpool create example /dev/da0 +# gpart create -s gpt ada1 +# gpart add -t freebsd-zfs ada1 +# zpool create example /dev/ada1p1 .... To view the new pool, review the output of `df`: [source,shell] .... -# df -Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/ad0s1a 2026030 235230 1628718 13% / -devfs 1 1 0 100% /dev -/dev/ad0s1d 54098308 1032846 48737598 2% /usr -example 17547136 0 17547136 0% /example +# df /example +Filesystem 1K-blocks Used Avail Capacity Mounted on +example 17547136 0 17547136 0% /example .... This output shows creating and mounting of the `example` pool, and that is now accessible as a file system. @@ -163,11 +163,8 @@ .... # zfs umount example/compressed # df -Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/ad0s1a 2026030 235232 1628716 13% / -devfs 1 1 0 100% /dev -/dev/ad0s1d 54098308 1032864 48737580 2% /usr -example 17547008 0 17547008 0% /example +Filesystem 1K-blocks Used Avail Capacity Mounted on +example 17547008 0 17547008 0% /example .... To re-mount the file system to make it accessible again, use `zfs mount` and verify with `df`: @@ -177,9 +174,6 @@ # zfs mount example/compressed # df Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/ad0s1a 2026030 235234 1628714 13% / -devfs 1 1 0 100% /dev -/dev/ad0s1d 54098308 1032864 48737580 2% /usr example 17547008 0 17547008 0% /example example/compressed 17547008 0 17547008 0% /example/compressed .... @@ -189,9 +183,9 @@ [source,shell] .... # mount -/dev/ad0s1a on / (ufs, local) +/dev/ada0p1 on / (ufs, local) devfs on /dev (devfs, local) -/dev/ad0s1d on /usr (ufs, local, soft-updates) +/dev/ada0p2 on /usr (ufs, local, soft-updates) example on /example (zfs, local) example/compressed on /example/compressed (zfs, local) .... @@ -212,13 +206,13 @@ [source,shell] .... # df -Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/ad0s1a 2026030 235234 1628714 13% / -devfs 1 1 0 100% /dev -/dev/ad0s1d 54098308 1032864 48737580 2% /usr -example 17547008 0 17547008 0% /example -example/compressed 17547008 0 17547008 0% /example/compressed -example/data 17547008 0 17547008 0% /example/data +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/ada0p1 2026030 235234 1628714 13% / +devfs 1 1 0 100% /dev +/dev/ada0p2 54098308 1032864 48737580 2% /usr +example 17547008 0 17547008 0% /example +example/compressed 17547008 0 17547008 0% /example/compressed +example/data 17547008 0 17547008 0% /example/data .... Notice that all file systems in the pool have the same available space. @@ -242,11 +236,19 @@ ZFS supports this feature in its pool design. RAID-Z pools require three or more disks but provide more usable space than mirrored pools. -This example creates a RAID-Z pool, specifying the disks to add to the pool: +This example creates a RAID-Z pool. +First the GPT partitions are created on each disk, then specify these GPT partitions to add to the pool using the `raidz` keyword: [source,shell] .... -# zpool create storage raidz da0 da1 da2 + +# gpart create -s gpt ada0 +# gpart add -t freebsd-zfs ada0 +# gpart create -s gpt ada1 +# gpart add -t freebsd-zfs ada1 +# gpart create -s gpt ada2 +# gpart add -t freebsd-zfs ada2 +# zpool create storage raidz ada0p1 ada1p1 ada2p1 .... [NOTE] @@ -333,16 +335,16 @@ [source,shell] .... # mount -/dev/ad0s1a on / (ufs, local) +/dev/ada0p1 on / (ufs, local) devfs on /dev (devfs, local) -/dev/ad0s1d on /usr (ufs, local, soft-updates) +/dev/ada0p2 on /usr (ufs, local, soft-updates) storage on /storage (zfs, local) storage/home on /home (zfs, local) # df Filesystem 1K-blocks Used Avail Capacity Mounted on -/dev/ad0s1a 2026030 235240 1628708 13% / +/dev/ada0p1 2026030 235240 1628708 13% / devfs 1 1 0 100% /dev -/dev/ad0s1d 54098308 1032826 48737618 2% /usr +/dev/ada0p2 54098308 1032826 48737618 2% /usr storage 26320512 0 26320512 0% /storage storage/home 26320512 0 26320512 0% /home .... @@ -391,26 +393,27 @@ NAME STATE READ WRITE CKSUM storage DEGRADED 0 0 0 raidz1 DEGRADED 0 0 0 - da0 ONLINE 0 0 0 - da1 OFFLINE 0 0 0 - da2 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 OFFLINE 0 0 0 + ada2p1 ONLINE 0 0 0 errors: No known data errors .... -"OFFLINE" shows the administrator took [.filename]#da1# offline using: +"OFFLINE" shows the administrator took [.filename]#ada1p1# offline using: [source,shell] .... -# zpool offline storage da1 +# zpool offline storage ada1p1 .... -Power down the computer now and replace [.filename]#da1#. -Power up the computer and return [.filename]#da1# to the pool: +Power down the computer now and replace [.filename]#ada1p1#. +Recreate the GPT paritition of type `freebsd-zfs` on the new disk. +Power up the computer and return [.filename]#ada1p1# to the pool: [source,shell] .... -# zpool replace storage da1 +# zpool replace storage ada1p1 .... Next, check the status again, this time without `-x` to display all pools: @@ -426,9 +429,9 @@ NAME STATE READ WRITE CKSUM storage ONLINE 0 0 0 raidz1 ONLINE 0 0 0 - da0 ONLINE 0 0 0 - da1 ONLINE 0 0 0 - da2 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 + ada2p1 ONLINE 0 0 0 errors: No known data errors .... @@ -472,9 +475,9 @@ NAME STATE READ WRITE CKSUM storage ONLINE 0 0 0 raidz1 ONLINE 0 0 0 - da0 ONLINE 0 0 0 - da1 ONLINE 0 0 0 - da2 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 + ada2p1 ONLINE 0 0 0 errors: No known data errors .... @@ -504,11 +507,11 @@ Although adding new vdevs expands a pool, the pool layout cannot change after pool creation. Instead, back up the data, destroy the pool, and recreate it. -Create a simple mirror pool: +Create a simple mirror pool on disks containing GPT partitions of type `freebsd-zfs`: [source,shell] .... -# zpool create mypool mirror /dev/ada1 /dev/ada2 +# zpool create mypool mirror /dev/ada1p1 /dev/ada2p1 # zpool status pool: mypool state: ONLINE @@ -518,8 +521,8 @@ NAME STATE READ WRITE CKSUM mypool ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada1 ONLINE 0 0 0 - ada2 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 + ada2p1 ONLINE 0 0 0 errors: No known data errors .... @@ -528,7 +531,7 @@ [source,shell] .... -# zpool create mypool mirror /dev/ada1 /dev/ada2 mirror /dev/ada3 /dev/ada4 +# zpool create mypool mirror /dev/ada1p1 /dev/ada2p1 mirror /dev/ada3p1 /dev/ada4p1 # zpool status pool: mypool state: ONLINE @@ -538,11 +541,11 @@ NAME STATE READ WRITE CKSUM mypool ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada1 ONLINE 0 0 0 - ada2 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 + ada2p1 ONLINE 0 0 0 mirror-1 ONLINE 0 0 0 - ada3 ONLINE 0 0 0 - ada4 ONLINE 0 0 0 + ada3p1 ONLINE 0 0 0 + ada4p1 ONLINE 0 0 0 errors: No known data errors .... @@ -559,7 +562,7 @@ [source,shell] .... -# zpool create mypool raidz2 /dev/ada0p3 /dev/ada1p3 /dev/ada2p3 /dev/ada3p3 /dev/ada4p3 /dev/ada5p3 +# zpool create mypool raidz2 /dev/ada0p1 /dev/ada1p1 /dev/ada2p1 /dev/ada3p1 /dev/ada4p1 /dev/ada5p1 # zpool status pool: mypool state: ONLINE @@ -569,12 +572,12 @@ NAME STATE READ WRITE CKSUM mypool ONLINE 0 0 0 raidz2-0 ONLINE 0 0 0 - ada0p3 ONLINE 0 0 0 - ada1p3 ONLINE 0 0 0 - ada2p3 ONLINE 0 0 0 - ada3p3 ONLINE 0 0 0 - ada4p3 ONLINE 0 0 0 - ada5p3 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 + ada2p1 ONLINE 0 0 0 + ada3p1 ONLINE 0 0 0 + ada4p1 ONLINE 0 0 0 + ada5p1 ONLINE 0 0 0 errors: No known data errors .... @@ -620,9 +623,9 @@ If you boot from pool 'mypool', you may need to update boot code on newly attached disk _ada1p3_. -Assuming you use GPT partitioning and _da0_ is your new boot disk you may use the following command: +Assuming you use GPT partitioning and _ada0_ is your new boot disk you may use the following command: - gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 da0 + gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 # gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada1 bootcode written to ada1 # zpool status @@ -819,9 +822,9 @@ When booting from the pool 'zroot', update the boot code on the newly attached disk 'ada2p3'. -Assuming GPT partitioning is used and [.filename]#da0# is the new boot disk, use the following command: +Assuming GPT partitioning is used and [.filename]#ada0# is the new boot disk, use the following command: - gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 da0 + gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada0 # gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 ada2 # zpool status pool: mypool @@ -985,7 +988,7 @@ [source,shell] .... -# zpool create healer mirror /dev/ada0 /dev/ada1 +# zpool create healer mirror /dev/ada0p1 /dev/ada1p1 # zpool status healer pool: healer state: ONLINE @@ -995,8 +998,8 @@ NAME STATE READ WRITE CKSUM healer ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 errors: No known data errors # zpool list @@ -1060,8 +1063,8 @@ NAME STATE READ WRITE CKSUM healer ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 1 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 1 errors: No known data errors .... @@ -1104,8 +1107,8 @@ NAME STATE READ WRITE CKSUM healer ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 627 (repairing) + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 627 (repairing) errors: No known data errors .... @@ -1129,8 +1132,8 @@ NAME STATE READ WRITE CKSUM healer ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 2.72K + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 2.72K errors: No known data errors .... @@ -1150,8 +1153,8 @@ NAME STATE READ WRITE CKSUM healer ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 errors: No known data errors .... @@ -1208,8 +1211,8 @@ action: The pool can be imported using its name or numeric identifier. config: - mypool ONLINE - ada2p3 ONLINE + mypool ONLINE + ada0 ONLINE .... Import the pool with an alternative root directory: @@ -1249,8 +1252,8 @@ NAME STATE READ WRITE CKSUM mypool ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 errors: No known data errors # zpool upgrade @@ -1297,8 +1300,8 @@ NAME STATE READ WRITE CKSUM mypool ONLINE 0 0 0 mirror-0 ONLINE 0 0 0 - ada0 ONLINE 0 0 0 - ada1 ONLINE 0 0 0 + ada0p1 ONLINE 0 0 0 + ada1p1 ONLINE 0 0 0 errors: No known data errors # zpool upgrade @@ -1368,7 +1371,7 @@ .... # zpool history History for 'tank': -2013-02-26.23:02:35 zpool create tank mirror /dev/ada0 /dev/ada1 +2013-02-26.23:02:35 zpool create tank mirror /dev/ada0p1 /dev/ada1p1 2013-02-27.18:50:58 zfs set atime=off tank 2013-02-27.18:51:09 zfs set checksum=fletcher4 tank 2013-02-27.18:51:18 zfs create tank/backup @@ -1401,13 +1404,13 @@ .... # zpool history -l History for 'tank': -2013-02-26.23:02:35 zpool create tank mirror /dev/ada0 /dev/ada1 [user 0 (root) on :global] +2013-02-26.23:02:35 zpool create tank mirror /dev/ada0p1 /dev/ada1p1 [user 0 (root) on :global] 2013-02-27.18:50:58 zfs set atime=off tank [user 0 (root) on myzfsbox:global] 2013-02-27.18:51:09 zfs set checksum=fletcher4 tank [user 0 (root) on myzfsbox:global] 2013-02-27.18:51:18 zfs create tank/backup [user 0 (root) on myzfsbox:global] .... -The output shows that the `root` user created the mirrored pool with disks [.filename]#/dev/ada0# and [.filename]#/dev/ada1#. +The output shows that the `root` user created the mirrored pool with disks [.filename]#/dev/ada0p1# and [.filename]#/dev/ada1p1#. The hostname `myzfsbox` is also shown in the commands after the pool's creation. The hostname display becomes important when exporting the pool from one system and importing on another. It's possible to distinguish the commands issued on the other system by the hostname recorded for each command. @@ -1451,8 +1454,8 @@ ----------------------- ----- ----- ----- ----- ----- ----- data 288G 1.53T 2 12 9.23K 61.5K mirror 288G 1.53T 2 12 9.23K 61.5K - ada1 - - 0 4 5.61K 61.7K - ada2 - - 1 4 5.04K 61.7K + ada1p1 - - 0 4 5.61K 61.7K + ada2p1 - - 1 4 5.04K 61.7K ----------------------- ----- ----- ----- ----- ----- ----- .... @@ -2468,7 +2471,7 @@ [source,shell] .... # zfs get used,compressratio,compression,logicalused mypool/compressed_dataset -NAME PROPERTY VALUE SOURCE +NAME PROPERTY VALUE SOURCE mypool/compressed_dataset used 449G - mypool/compressed_dataset compressratio 1.11x - mypool/compressed_dataset compression lz4 local @@ -2798,7 +2801,7 @@ |[[zfs-term-vdev]]vdev Types a|A pool consists of one or more vdevs, which themselves are a single disk or a group of disks, transformed to a RAID. When using a lot of vdevs, ZFS spreads data across the vdevs to increase performance and maximize usable space. All vdevs must be at least 128 MB in size. -* [[zfs-term-vdev-disk]] _Disk_ - The most basic vdev type is a standard block device. This can be an entire disk (such as [.filename]#/dev/ada0# or [.filename]#/dev/da0#) or a partition ([.filename]#/dev/ada0p3#). On FreeBSD, there is no performance penalty for using a partition rather than the entire disk. This differs from recommendations made by the Solaris documentation. +* [[zfs-term-vdev-disk]] _Disk_ - The most basic vdev type is a standard block device. This can be an entire disk (such as [.filename]#/dev/ada0# or a partition ([.filename]#/dev/ada0p3#). On FreeBSD, there is no performance penalty for using a partition rather than the entire disk. This differs from recommendations made by the Solaris documentation. + [CAUTION] ====