9763 zfs(1M): broken formatting in allow/unallow description
1 ZFS(1M) Maintenance Commands ZFS(1M) 2 3 NAME 4 zfs - configures ZFS file systems 5 6 SYNOPSIS 7 zfs [-?] 8 zfs create [-p] [-o property=value]... filesystem 9 zfs create [-ps] [-b blocksize] [-o property=value]... -V size volume 10 zfs destroy [-Rfnprv] filesystem|volume 11 zfs destroy [-Rdnprv] filesystem|volume@snap[%snap[,snap[%snap]]]... 12 zfs destroy filesystem|volume#bookmark 13 zfs snapshot [-r] [-o property=value]... 14 filesystem@snapname|volume@snapname... 15 zfs rollback [-Rfr] snapshot 16 zfs clone [-p] [-o property=value]... snapshot filesystem|volume 17 zfs promote clone-filesystem 18 zfs rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot 19 zfs rename [-fp] filesystem|volume filesystem|volume 20 zfs rename -r snapshot snapshot 21 zfs list [-r|-d depth] [-Hp] [-o property[,property]...] [-s property]... 22 [-S property]... [-t type[,type]...] [filesystem|volume|snapshot]... 23 zfs remap filesystem|volume 24 zfs set property=value [property=value]... filesystem|volume|snapshot... 25 zfs get [-r|-d depth] [-Hp] [-o field[,field]...] [-s source[,source]...] 26 [-t type[,type]...] all | property[,property]... 27 filesystem|volume|snapshot|bookmark... 28 zfs inherit [-rS] property filesystem|volume|snapshot... 29 zfs upgrade 30 zfs upgrade -v 31 zfs upgrade [-r] [-V version] -a | filesystem 32 zfs userspace [-Hinp] [-o field[,field]...] [-s field]... [-S field]... 33 [-t type[,type]...] filesystem|snapshot 34 zfs groupspace [-Hinp] [-o field[,field]...] [-s field]... [-S field]... 35 [-t type[,type]...] filesystem|snapshot 36 zfs mount 37 zfs mount [-Ov] [-o options] -a | filesystem 38 zfs unmount [-f] -a | filesystem|mountpoint 39 zfs share -a | filesystem 40 zfs unshare -a | filesystem|mountpoint 41 zfs bookmark snapshot bookmark 42 zfs send [-DLPRcenpv] [[-I|-i] snapshot] snapshot 43 zfs send [-Lce] [-i snapshot|bookmark] filesystem|volume|snapshot 44 zfs send [-Penv] -t receive_resume_token 45 zfs receive [-Fnsuv] [-o origin=snapshot] filesystem|volume|snapshot 46 zfs receive [-Fnsuv] [-d|-e] [-o origin=snapshot] filesystem 47 zfs receive -A filesystem|volume 48 zfs allow filesystem|volume 49 zfs allow [-dglu] user|group[,user|group]... 50 perm|@setname[,perm|@setname]... filesystem|volume 51 zfs allow [-dl] -e|everyone perm|@setname[,perm|@setname]... 52 filesystem|volume 53 zfs allow -c perm|@setname[,perm|@setname]... filesystem|volume 54 zfs allow -s @setname perm|@setname[,perm|@setname]... filesystem|volume 55 zfs unallow [-dglru] user|group[,user|group]... 56 [perm|@setname[,perm|@setname]...] filesystem|volume 57 zfs unallow [-dlr] -e|everyone [perm|@setname[,perm|@setname]...] 58 filesystem|volume 59 zfs unallow [-r] -c [perm|@setname[,perm|@setname]...] filesystem|volume 60 zfs unallow [-r] -s -@setname [perm|@setname[,perm|@setname]...] 61 filesystem|volume 62 zfs hold [-r] tag snapshot... 63 zfs holds [-r] snapshot... 64 zfs release [-r] tag snapshot... 65 zfs diff [-FHt] snapshot snapshot|filesystem 66 zfs program [-n] [-t timeout] [-m memory_limit] pool script [arg1 ...] 67 68 DESCRIPTION 69 The zfs command configures ZFS datasets within a ZFS storage pool, as 70 described in zpool(1M). A dataset is identified by a unique path within 71 the ZFS namespace. For example: 72 73 pool/{filesystem,volume,snapshot} 74 75 where the maximum length of a dataset name is MAXNAMELEN (256 bytes) and 76 the maximum amount of nesting allowed in a path is 50 levels deep. 77 78 A dataset can be one of the following: 79 80 file system A ZFS dataset of type filesystem can be mounted within the 81 standard system namespace and behaves like other file 82 systems. While ZFS file systems are designed to be POSIX 83 compliant, known issues exist that prevent compliance in 84 some cases. Applications that depend on standards 85 conformance might fail due to non-standard behavior when 86 checking file system free space. 87 88 volume A logical volume exported as a raw or block device. This 89 type of dataset should only be used under special 90 circumstances. File systems are typically used in most 91 environments. 92 93 snapshot A read-only version of a file system or volume at a given 94 point in time. It is specified as filesystem@name or 95 volume@name. 96 97 ZFS File System Hierarchy 98 A ZFS storage pool is a logical collection of devices that provide space 99 for datasets. A storage pool is also the root of the ZFS file system 100 hierarchy. 101 102 The root of the pool can be accessed as a file system, such as mounting 103 and unmounting, taking snapshots, and setting properties. The physical 104 storage characteristics, however, are managed by the zpool(1M) command. 105 106 See zpool(1M) for more information on creating and administering pools. 107 108 Snapshots 109 A snapshot is a read-only copy of a file system or volume. Snapshots can 110 be created extremely quickly, and initially consume no additional space 111 within the pool. As data within the active dataset changes, the snapshot 112 consumes more data than would otherwise be shared with the active 113 dataset. 114 115 Snapshots can have arbitrary names. Snapshots of volumes can be cloned 116 or rolled back, but cannot be accessed independently. 117 118 File system snapshots can be accessed under the .zfs/snapshot directory 119 in the root of the file system. Snapshots are automatically mounted on 120 demand and may be unmounted at regular intervals. The visibility of the 121 .zfs directory can be controlled by the snapdir property. 122 123 Clones 124 A clone is a writable volume or file system whose initial contents are 125 the same as another dataset. As with snapshots, creating a clone is 126 nearly instantaneous, and initially consumes no additional space. 127 128 Clones can only be created from a snapshot. When a snapshot is cloned, 129 it creates an implicit dependency between the parent and child. Even 130 though the clone is created somewhere else in the dataset hierarchy, the 131 original snapshot cannot be destroyed as long as a clone exists. The 132 origin property exposes this dependency, and the destroy command lists 133 any such dependencies, if they exist. 134 135 The clone parent-child dependency relationship can be reversed by using 136 the promote subcommand. This causes the "origin" file system to become a 137 clone of the specified file system, which makes it possible to destroy 138 the file system that the clone was created from. 139 140 Mount Points 141 Creating a ZFS file system is a simple operation, so the number of file 142 systems per system is likely to be numerous. To cope with this, ZFS 143 automatically manages mounting and unmounting file systems without the 144 need to edit the /etc/vfstab file. All automatically managed file 145 systems are mounted by ZFS at boot time. 146 147 By default, file systems are mounted under /path, where path is the name 148 of the file system in the ZFS namespace. Directories are created and 149 destroyed as needed. 150 151 A file system can also have a mount point set in the mountpoint property. 152 This directory is created as needed, and ZFS automatically mounts the 153 file system when the zfs mount -a command is invoked (without editing 154 /etc/vfstab). The mountpoint property can be inherited, so if pool/home 155 has a mount point of /export/stuff, then pool/home/user automatically 156 inherits a mount point of /export/stuff/user. 157 158 A file system mountpoint property of none prevents the file system from 159 being mounted. 160 161 If needed, ZFS file systems can also be managed with traditional tools 162 (mount, umount, /etc/vfstab). If a file system's mount point is set to 163 legacy, ZFS makes no attempt to manage the file system, and the 164 administrator is responsible for mounting and unmounting the file system. 165 166 Zones 167 A ZFS file system can be added to a non-global zone by using the zonecfg 168 add fs subcommand. A ZFS file system that is added to a non-global zone 169 must have its mountpoint property set to legacy. 170 171 The physical properties of an added file system are controlled by the 172 global administrator. However, the zone administrator can create, 173 modify, or destroy files within the added file system, depending on how 174 the file system is mounted. 175 176 A dataset can also be delegated to a non-global zone by using the zonecfg 177 add dataset subcommand. You cannot delegate a dataset to one zone and 178 the children of the same dataset to another zone. The zone administrator 179 can change properties of the dataset or any of its children. However, 180 the quota, filesystem_limit and snapshot_limit properties of the 181 delegated dataset can be modified only by the global administrator. 182 183 A ZFS volume can be added as a device to a non-global zone by using the 184 zonecfg add device subcommand. However, its physical properties can be 185 modified only by the global administrator. 186 187 For more information about zonecfg syntax, see zonecfg(1M). 188 189 After a dataset is delegated to a non-global zone, the zoned property is 190 automatically set. A zoned file system cannot be mounted in the global 191 zone, since the zone administrator might have to set the mount point to 192 an unacceptable value. 193 194 The global administrator can forcibly clear the zoned property, though 195 this should be done with extreme care. The global administrator should 196 verify that all the mount points are acceptable before clearing the 197 property. 198 199 Native Properties 200 Properties are divided into two types, native properties and user-defined 201 (or "user") properties. Native properties either export internal 202 statistics or control ZFS behavior. In addition, native properties are 203 either editable or read-only. User properties have no effect on ZFS 204 behavior, but you can use them to annotate datasets in a way that is 205 meaningful in your environment. For more information about user 206 properties, see the User Properties section, below. 207 208 Every dataset has a set of properties that export statistics about the 209 dataset as well as control various behaviors. Properties are inherited 210 from the parent unless overridden by the child. Some properties apply 211 only to certain types of datasets (file systems, volumes, or snapshots). 212 213 The values of numeric properties can be specified using human-readable 214 suffixes (for example, k, KB, M, Gb, and so forth, up to Z for 215 zettabyte). The following are all valid (and equal) specifications: 216 1536M, 1.5g, 1.50GB. 217 218 The values of non-numeric properties are case sensitive and must be 219 lowercase, except for mountpoint, sharenfs, and sharesmb. 220 221 The following native properties consist of read-only statistics about the 222 dataset. These properties can be neither set, nor inherited. Native 223 properties apply to all dataset types unless otherwise noted. 224 225 available The amount of space available to the dataset and 226 all its children, assuming that there is no other 227 activity in the pool. Because space is shared 228 within a pool, availability can be limited by any 229 number of factors, including physical pool size, 230 quotas, reservations, or other datasets within the 231 pool. 232 233 This property can also be referred to by its 234 shortened column name, avail. 235 236 compressratio For non-snapshots, the compression ratio achieved 237 for the used space of this dataset, expressed as a 238 multiplier. The used property includes descendant 239 datasets, and, for clones, does not include the 240 space shared with the origin snapshot. For 241 snapshots, the compressratio is the same as the 242 refcompressratio property. Compression can be 243 turned on by running: zfs set compression=on 244 dataset. The default value is off. 245 246 createtxg The transaction group (txg) in which the dataset 247 was created. Bookmarks have the same createtxg as 248 the snapshot they are initially tied to. This 249 property is suitable for ordering a list of 250 snapshots, e.g. for incremental send and receive. 251 252 creation The time this dataset was created. 253 254 clones For snapshots, this property is a comma-separated 255 list of filesystems or volumes which are clones of 256 this snapshot. The clones' origin property is this 257 snapshot. If the clones property is not empty, 258 then this snapshot can not be destroyed (even with 259 the -r or -f options). 260 261 defer_destroy This property is on if the snapshot has been marked 262 for deferred destroy by using the zfs destroy -d 263 command. Otherwise, the property is off. 264 265 filesystem_count The total number of filesystems and volumes that 266 exist under this location in the dataset tree. 267 This value is only available when a 268 filesystem_limit has been set somewhere in the tree 269 under which the dataset resides. 270 271 guid The 64 bit GUID of this dataset or bookmark which 272 does not change over its entire lifetime. When a 273 snapshot is sent to another pool, the received 274 snapshot has the same GUID. Thus, the guid is 275 suitable to identify a snapshot across pools. 276 277 logicalreferenced The amount of space that is "logically" accessible 278 by this dataset. See the referenced property. The 279 logical space ignores the effect of the compression 280 and copies properties, giving a quantity closer to 281 the amount of data that applications see. However, 282 it does include space consumed by metadata. 283 284 This property can also be referred to by its 285 shortened column name, lrefer. 286 287 logicalused The amount of space that is "logically" consumed by 288 this dataset and all its descendents. See the used 289 property. The logical space ignores the effect of 290 the compression and copies properties, giving a 291 quantity closer to the amount of data that 292 applications see. However, it does include space 293 consumed by metadata. 294 295 This property can also be referred to by its 296 shortened column name, lused. 297 298 mounted For file systems, indicates whether the file system 299 is currently mounted. This property can be either 300 yes or no. 301 302 origin For cloned file systems or volumes, the snapshot 303 from which the clone was created. See also the 304 clones property. 305 306 receive_resume_token For filesystems or volumes which have saved 307 partially-completed state from zfs receive -s, this 308 opaque token can be provided to zfs send -t to 309 resume and complete the zfs receive. 310 311 referenced The amount of data that is accessible by this 312 dataset, which may or may not be shared with other 313 datasets in the pool. When a snapshot or clone is 314 created, it initially references the same amount of 315 space as the file system or snapshot it was created 316 from, since its contents are identical. 317 318 This property can also be referred to by its 319 shortened column name, refer. 320 321 refcompressratio The compression ratio achieved for the referenced 322 space of this dataset, expressed as a multiplier. 323 See also the compressratio property. 324 325 snapshot_count The total number of snapshots that exist under this 326 location in the dataset tree. This value is only 327 available when a snapshot_limit has been set 328 somewhere in the tree under which the dataset 329 resides. 330 331 type The type of dataset: filesystem, volume, or 332 snapshot. 333 334 used The amount of space consumed by this dataset and 335 all its descendents. This is the value that is 336 checked against this dataset's quota and 337 reservation. The space used does not include this 338 dataset's reservation, but does take into account 339 the reservations of any descendent datasets. The 340 amount of space that a dataset consumes from its 341 parent, as well as the amount of space that is 342 freed if this dataset is recursively destroyed, is 343 the greater of its space used and its reservation. 344 345 The used space of a snapshot (see the Snapshots 346 section) is space that is referenced exclusively by 347 this snapshot. If this snapshot is destroyed, the 348 amount of used space will be freed. Space that is 349 shared by multiple snapshots isn't accounted for in 350 this metric. When a snapshot is destroyed, space 351 that was previously shared with this snapshot can 352 become unique to snapshots adjacent to it, thus 353 changing the used space of those snapshots. The 354 used space of the latest snapshot can also be 355 affected by changes in the file system. Note that 356 the used space of a snapshot is a subset of the 357 written space of the snapshot. 358 359 The amount of space used, available, or referenced 360 does not take into account pending changes. 361 Pending changes are generally accounted for within 362 a few seconds. Committing a change to a disk using 363 fsync(3C) or O_SYNC does not necessarily guarantee 364 that the space usage information is updated 365 immediately. 366 367 usedby* The usedby* properties decompose the used 368 properties into the various reasons that space is 369 used. Specifically, used = usedbychildren + 370 usedbydataset + usedbyrefreservation + 371 usedbysnapshots. These properties are only 372 available for datasets created on zpool "version 373 13" pools. 374 375 usedbychildren The amount of space used by children of this 376 dataset, which would be freed if all the dataset's 377 children were destroyed. 378 379 usedbydataset The amount of space used by this dataset itself, 380 which would be freed if the dataset were destroyed 381 (after first removing any refreservation and 382 destroying any necessary snapshots or descendents). 383 384 usedbyrefreservation The amount of space used by a refreservation set on 385 this dataset, which would be freed if the 386 refreservation was removed. 387 388 usedbysnapshots The amount of space consumed by snapshots of this 389 dataset. In particular, it is the amount of space 390 that would be freed if all of this dataset's 391 snapshots were destroyed. Note that this is not 392 simply the sum of the snapshots' used properties 393 because space can be shared by multiple snapshots. 394 395 userused@user The amount of space consumed by the specified user 396 in this dataset. Space is charged to the owner of 397 each file, as displayed by ls -l. The amount of 398 space charged is displayed by du and ls -s. See 399 the zfs userspace subcommand for more information. 400 401 Unprivileged users can access only their own space 402 usage. The root user, or a user who has been 403 granted the userused privilege with zfs allow, can 404 access everyone's usage. 405 406 The userused@... properties are not displayed by 407 zfs get all. The user's name must be appended 408 after the @ symbol, using one of the following 409 forms: 410 411 o POSIX name (for example, joe) 412 413 o POSIX numeric ID (for example, 789) 414 415 o SID name (for example, joe.smith@mydomain) 416 417 o SID numeric ID (for example, S-1-123-456-789) 418 419 userrefs This property is set to the number of user holds on 420 this snapshot. User holds are set by using the zfs 421 hold command. 422 423 groupused@group The amount of space consumed by the specified group 424 in this dataset. Space is charged to the group of 425 each file, as displayed by ls -l. See the 426 userused@user property for more information. 427 428 Unprivileged users can only access their own 429 groups' space usage. The root user, or a user who 430 has been granted the groupused privilege with zfs 431 allow, can access all groups' usage. 432 433 volblocksize For volumes, specifies the block size of the 434 volume. The blocksize cannot be changed once the 435 volume has been written, so it should be set at 436 volume creation time. The default blocksize for 437 volumes is 8 Kbytes. Any power of 2 from 512 bytes 438 to 128 Kbytes is valid. 439 440 This property can also be referred to by its 441 shortened column name, volblock. 442 443 written The amount of space referenced by this dataset, 444 that was written since the previous snapshot (i.e. 445 that is not referenced by the previous snapshot). 446 447 written@snapshot The amount of referenced space written to this 448 dataset since the specified snapshot. This is the 449 space that is referenced by this dataset but was 450 not referenced by the specified snapshot. 451 452 The snapshot may be specified as a short snapshot 453 name (just the part after the @), in which case it 454 will be interpreted as a snapshot in the same 455 filesystem as this dataset. The snapshot may be a 456 full snapshot name (filesystem@snapshot), which for 457 clones may be a snapshot in the origin's filesystem 458 (or the origin of the origin's filesystem, etc.) 459 460 The following native properties can be used to change the behavior of a 461 ZFS dataset. 462 463 aclinherit=discard|noallow|restricted|passthrough|passthrough-x 464 Controls how ACEs are inherited when files and directories are created. 465 466 discard does not inherit any ACEs. 467 468 noallow only inherits inheritable ACEs that specify "deny" 469 permissions. 470 471 restricted default, removes the write_acl and write_owner 472 permissions when the ACE is inherited. 473 474 passthrough inherits all inheritable ACEs without any modifications. 475 476 passthrough-x same meaning as passthrough, except that the owner@, 477 group@, and everyone@ ACEs inherit the execute 478 permission only if the file creation mode also requests 479 the execute bit. 480 481 When the property value is set to passthrough, files are created with a 482 mode determined by the inheritable ACEs. If no inheritable ACEs exist 483 that affect the mode, then the mode is set in accordance to the 484 requested mode from the application. 485 486 aclmode=discard|groupmask|passthrough|restricted 487 Controls how an ACL is modified during chmod(2) and how inherited ACEs 488 are modified by the file creation mode. 489 490 discard default, deletes all ACEs except for those representing 491 the mode of the file or directory requested by chmod(2). 492 493 groupmask reduces permissions granted by all ALLOW entries found in 494 the ACL such that they are no greater than the group 495 permissions specified by the mode. 496 497 passthrough indicates that no changes are made to the ACL other than 498 creating or updating the necessary ACEs to represent the 499 new mode of the file or directory. 500 501 restricted causes the chmod(2) operation to return an error when used 502 on any file or directory which has a non-trivial ACL, with 503 entries in addition to those that represent the mode. 504 505 chmod(2) is required to change the set user ID, set group ID, or sticky 506 bit on a file or directory, as they do not have equivalent ACEs. In 507 order to use chmod(2) on a file or directory with a non-trivial ACL 508 when aclmode is set to restricted, you must first remove all ACEs 509 except for those that represent the current mode. 510 511 atime=on|off 512 Controls whether the access time for files is updated when they are 513 read. Turning this property off avoids producing write traffic when 514 reading files and can result in significant performance gains, though 515 it might confuse mailers and other similar utilities. The default 516 value is on. 517 518 canmount=on|off|noauto 519 If this property is set to off, the file system cannot be mounted, and 520 is ignored by zfs mount -a. Setting this property to off is similar to 521 setting the mountpoint property to none, except that the dataset still 522 has a normal mountpoint property, which can be inherited. Setting this 523 property to off allows datasets to be used solely as a mechanism to 524 inherit properties. One example of setting canmount=off is to have two 525 datasets with the same mountpoint, so that the children of both 526 datasets appear in the same directory, but might have different 527 inherited characteristics. 528 529 When set to noauto, a dataset can only be mounted and unmounted 530 explicitly. The dataset is not mounted automatically when the dataset 531 is created or imported, nor is it mounted by the zfs mount -a command 532 or unmounted by the zfs unmount -a command. 533 534 This property is not inherited. 535 536 checksum=on|off|fletcher2|fletcher4|sha256|noparity|sha512|skein|edonr 537 Controls the checksum used to verify data integrity. The default value 538 is on, which automatically selects an appropriate algorithm (currently, 539 fletcher4, but this may change in future releases). The value off 540 disables integrity checking on user data. The value noparity not only 541 disables integrity but also disables maintaining parity for user data. 542 This setting is used internally by a dump device residing on a RAID-Z 543 pool and should not be used by any other dataset. Disabling checksums 544 is NOT a recommended practice. 545 546 The sha512, skein, and edonr checksum algorithms require enabling the 547 appropriate features on the pool. Please see zpool-features(5) for 548 more information on these algorithms. 549 550 Changing this property affects only newly-written data. 551 552 compression=on|off|gzip|gzip-N|lz4|lzjb|zle 553 Controls the compression algorithm used for this dataset. 554 555 Setting compression to on indicates that the current default 556 compression algorithm should be used. The default balances compression 557 and decompression speed, with compression ratio and is expected to work 558 well on a wide variety of workloads. Unlike all other settings for 559 this property, on does not select a fixed compression type. As new 560 compression algorithms are added to ZFS and enabled on a pool, the 561 default compression algorithm may change. The current default 562 compression algorithm is either lzjb or, if the lz4_compress feature is 563 enabled, lz4. 564 565 The lz4 compression algorithm is a high-performance replacement for the 566 lzjb algorithm. It features significantly faster compression and 567 decompression, as well as a moderately higher compression ratio than 568 lzjb, but can only be used on pools with the lz4_compress feature set 569 to enabled. See zpool-features(5) for details on ZFS feature flags and 570 the lz4_compress feature. 571 572 The lzjb compression algorithm is optimized for performance while 573 providing decent data compression. 574 575 The gzip compression algorithm uses the same compression as the gzip(1) 576 command. You can specify the gzip level by using the value gzip-N, 577 where N is an integer from 1 (fastest) to 9 (best compression ratio). 578 Currently, gzip is equivalent to gzip-6 (which is also the default for 579 gzip(1)). 580 581 The zle compression algorithm compresses runs of zeros. 582 583 This property can also be referred to by its shortened column name 584 compress. Changing this property affects only newly-written data. 585 586 copies=1|2|3 587 Controls the number of copies of data stored for this dataset. These 588 copies are in addition to any redundancy provided by the pool, for 589 example, mirroring or RAID-Z. The copies are stored on different 590 disks, if possible. The space used by multiple copies is charged to 591 the associated file and dataset, changing the used property and 592 counting against quotas and reservations. 593 594 Changing this property only affects newly-written data. Therefore, set 595 this property at file system creation time by using the -o copies=N 596 option. 597 598 devices=on|off 599 Controls whether device nodes can be opened on this file system. The 600 default value is on. 601 602 exec=on|off 603 Controls whether processes can be executed from within this file 604 system. The default value is on. 605 606 filesystem_limit=count|none 607 Limits the number of filesystems and volumes that can exist under this 608 point in the dataset tree. The limit is not enforced if the user is 609 allowed to change the limit. Setting a filesystem_limit to on a 610 descendent of a filesystem that already has a filesystem_limit does not 611 override the ancestor's filesystem_limit, but rather imposes an 612 additional limit. This feature must be enabled to be used (see 613 zpool-features(5)). 614 615 mountpoint=path|none|legacy 616 Controls the mount point used for this file system. See the Mount 617 Points section for more information on how this property is used. 618 619 When the mountpoint property is changed for a file system, the file 620 system and any children that inherit the mount point are unmounted. If 621 the new value is legacy, then they remain unmounted. Otherwise, they 622 are automatically remounted in the new location if the property was 623 previously legacy or none, or if they were mounted before the property 624 was changed. In addition, any shared file systems are unshared and 625 shared in the new location. 626 627 nbmand=on|off 628 Controls whether the file system should be mounted with nbmand (Non 629 Blocking mandatory locks). This is used for SMB clients. Changes to 630 this property only take effect when the file system is umounted and 631 remounted. See mount(1M) for more information on nbmand mounts. 632 633 primarycache=all|none|metadata 634 Controls what is cached in the primary cache (ARC). If this property 635 is set to all, then both user data and metadata is cached. If this 636 property is set to none, then neither user data nor metadata is cached. 637 If this property is set to metadata, then only metadata is cached. The 638 default value is all. 639 640 quota=size|none 641 Limits the amount of space a dataset and its descendents can consume. 642 This property enforces a hard limit on the amount of space used. This 643 includes all space consumed by descendents, including file systems and 644 snapshots. Setting a quota on a descendent of a dataset that already 645 has a quota does not override the ancestor's quota, but rather imposes 646 an additional limit. 647 648 Quotas cannot be set on volumes, as the volsize property acts as an 649 implicit quota. 650 651 snapshot_limit=count|none 652 Limits the number of snapshots that can be created on a dataset and its 653 descendents. Setting a snapshot_limit on a descendent of a dataset 654 that already has a snapshot_limit does not override the ancestor's 655 snapshot_limit, but rather imposes an additional limit. The limit is 656 not enforced if the user is allowed to change the limit. For example, 657 this means that recursive snapshots taken from the global zone are 658 counted against each delegated dataset within a zone. This feature 659 must be enabled to be used (see zpool-features(5)). 660 661 userquota@user=size|none 662 Limits the amount of space consumed by the specified user. User space 663 consumption is identified by the userspace@user property. 664 665 Enforcement of user quotas may be delayed by several seconds. This 666 delay means that a user might exceed their quota before the system 667 notices that they are over quota and begins to refuse additional writes 668 with the EDQUOT error message. See the zfs userspace subcommand for 669 more information. 670 671 Unprivileged users can only access their own groups' space usage. The 672 root user, or a user who has been granted the userquota privilege with 673 zfs allow, can get and set everyone's quota. 674 675 This property is not available on volumes, on file systems before 676 version 4, or on pools before version 15. The userquota@... properties 677 are not displayed by zfs get all. The user's name must be appended 678 after the @ symbol, using one of the following forms: 679 680 o POSIX name (for example, joe) 681 682 o POSIX numeric ID (for example, 789) 683 684 o SID name (for example, joe.smith@mydomain) 685 686 o SID numeric ID (for example, S-1-123-456-789) 687 688 groupquota@group=size|none 689 Limits the amount of space consumed by the specified group. Group 690 space consumption is identified by the groupused@group property. 691 692 Unprivileged users can access only their own groups' space usage. The 693 root user, or a user who has been granted the groupquota privilege with 694 zfs allow, can get and set all groups' quotas. 695 696 readonly=on|off 697 Controls whether this dataset can be modified. The default value is 698 off. 699 700 This property can also be referred to by its shortened column name, 701 rdonly. 702 703 recordsize=size 704 Specifies a suggested block size for files in the file system. This 705 property is designed solely for use with database workloads that access 706 files in fixed-size records. ZFS automatically tunes block sizes 707 according to internal algorithms optimized for typical access patterns. 708 709 For databases that create very large files but access them in small 710 random chunks, these algorithms may be suboptimal. Specifying a 711 recordsize greater than or equal to the record size of the database can 712 result in significant performance gains. Use of this property for 713 general purpose file systems is strongly discouraged, and may adversely 714 affect performance. 715 716 The size specified must be a power of two greater than or equal to 512 717 and less than or equal to 128 Kbytes. If the large_blocks feature is 718 enabled on the pool, the size may be up to 1 Mbyte. See 719 zpool-features(5) for details on ZFS feature flags. 720 721 Changing the file system's recordsize affects only files created 722 afterward; existing files are unaffected. 723 724 This property can also be referred to by its shortened column name, 725 recsize. 726 727 redundant_metadata=all|most 728 Controls what types of metadata are stored redundantly. ZFS stores an 729 extra copy of metadata, so that if a single block is corrupted, the 730 amount of user data lost is limited. This extra copy is in addition to 731 any redundancy provided at the pool level (e.g. by mirroring or 732 RAID-Z), and is in addition to an extra copy specified by the copies 733 property (up to a total of 3 copies). For example if the pool is 734 mirrored, copies=2, and redundant_metadata=most, then ZFS stores 6 735 copies of most metadata, and 4 copies of data and some metadata. 736 737 When set to all, ZFS stores an extra copy of all metadata. If a single 738 on-disk block is corrupt, at worst a single block of user data (which 739 is recordsize bytes long) can be lost. 740 741 When set to most, ZFS stores an extra copy of most types of metadata. 742 This can improve performance of random writes, because less metadata 743 must be written. In practice, at worst about 100 blocks (of recordsize 744 bytes each) of user data can be lost if a single on-disk block is 745 corrupt. The exact behavior of which metadata blocks are stored 746 redundantly may change in future releases. 747 748 The default value is all. 749 750 refquota=size|none 751 Limits the amount of space a dataset can consume. This property 752 enforces a hard limit on the amount of space used. This hard limit 753 does not include space used by descendents, including file systems and 754 snapshots. 755 756 refreservation=size|none|auto 757 The minimum amount of space guaranteed to a dataset, not including its 758 descendents. When the amount of space used is below this value, the 759 dataset is treated as if it were taking up the amount of space 760 specified by refreservation. The refreservation reservation is 761 accounted for in the parent datasets' space used, and counts against 762 the parent datasets' quotas and reservations. 763 764 If refreservation is set, a snapshot is only allowed if there is enough 765 free pool space outside of this reservation to accommodate the current 766 number of "referenced" bytes in the dataset. 767 768 If refreservation is set to auto, a volume is thick provisioned (or 769 "not sparse"). refreservation=auto is only supported on volumes. See 770 volsize in the Native Properties section for more information about 771 sparse volumes. 772 773 This property can also be referred to by its shortened column name, 774 refreserv. 775 776 reservation=size|none 777 The minimum amount of space guaranteed to a dataset and its 778 descendants. When the amount of space used is below this value, the 779 dataset is treated as if it were taking up the amount of space 780 specified by its reservation. Reservations are accounted for in the 781 parent datasets' space used, and count against the parent datasets' 782 quotas and reservations. 783 784 This property can also be referred to by its shortened column name, 785 reserv. 786 787 secondarycache=all|none|metadata 788 Controls what is cached in the secondary cache (L2ARC). If this 789 property is set to all, then both user data and metadata is cached. If 790 this property is set to none, then neither user data nor metadata is 791 cached. If this property is set to metadata, then only metadata is 792 cached. The default value is all. 793 794 setuid=on|off 795 Controls whether the setuid bit is respected for the file system. The 796 default value is on. 797 798 sharesmb=on|off|opts 799 Controls whether the file system is shared via SMB, and what options 800 are to be used. A file system with the sharesmb property set to off is 801 managed through traditional tools such as sharemgr(1M). Otherwise, the 802 file system is automatically shared and unshared with the zfs share and 803 zfs unshare commands. If the property is set to on, the sharemgr(1M) 804 command is invoked with no options. Otherwise, the sharemgr(1M) 805 command is invoked with options equivalent to the contents of this 806 property. 807 808 Because SMB shares requires a resource name, a unique resource name is 809 constructed from the dataset name. The constructed name is a copy of 810 the dataset name except that the characters in the dataset name, which 811 would be invalid in the resource name, are replaced with underscore (_) 812 characters. A pseudo property "name" is also supported that allows you 813 to replace the data set name with a specified name. The specified name 814 is then used to replace the prefix dataset in the case of inheritance. 815 For example, if the dataset data/home/john is set to name=john, then 816 data/home/john has a resource name of john. If a child dataset 817 data/home/john/backups is shared, it has a resource name of 818 john_backups. 819 820 When SMB shares are created, the SMB share name appears as an entry in 821 the .zfs/shares directory. You can use the ls or chmod command to 822 display the share-level ACLs on the entries in this directory. 823 824 When the sharesmb property is changed for a dataset, the dataset and 825 any children inheriting the property are re-shared with the new 826 options, only if the property was previously set to off, or if they 827 were shared before the property was changed. If the new property is 828 set to off, the file systems are unshared. 829 830 sharenfs=on|off|opts 831 Controls whether the file system is shared via NFS, and what options 832 are to be used. A file system with a sharenfs property of off is 833 managed through traditional tools such as share(1M), unshare(1M), and 834 dfstab(4). Otherwise, the file system is automatically shared and 835 unshared with the zfs share and zfs unshare commands. If the property 836 is set to on, share(1M) command is invoked with no options. Otherwise, 837 the share(1M) command is invoked with options equivalent to the 838 contents of this property. 839 840 When the sharenfs property is changed for a dataset, the dataset and 841 any children inheriting the property are re-shared with the new 842 options, only if the property was previously off, or if they were 843 shared before the property was changed. If the new property is off, 844 the file systems are unshared. 845 846 logbias=latency|throughput 847 Provide a hint to ZFS about handling of synchronous requests in this 848 dataset. If logbias is set to latency (the default), ZFS will use pool 849 log devices (if configured) to handle the requests at low latency. If 850 logbias is set to throughput, ZFS will not use configured pool log 851 devices. ZFS will instead optimize synchronous operations for global 852 pool throughput and efficient use of resources. 853 854 snapdir=hidden|visible 855 Controls whether the .zfs directory is hidden or visible in the root of 856 the file system as discussed in the Snapshots section. The default 857 value is hidden. 858 859 sync=standard|always|disabled 860 Controls the behavior of synchronous requests (e.g. fsync, O_DSYNC). 861 standard is the POSIX specified behavior of ensuring all synchronous 862 requests are written to stable storage and all devices are flushed to 863 ensure data is not cached by device controllers (this is the default). 864 always causes every file system transaction to be written and flushed 865 before its system call returns. This has a large performance penalty. 866 disabled disables synchronous requests. File system transactions are 867 only committed to stable storage periodically. This option will give 868 the highest performance. However, it is very dangerous as ZFS would be 869 ignoring the synchronous transaction demands of applications such as 870 databases or NFS. Administrators should only use this option when the 871 risks are understood. 872 873 version=N|current 874 The on-disk version of this file system, which is independent of the 875 pool version. This property can only be set to later supported 876 versions. See the zfs upgrade command. 877 878 volsize=size 879 For volumes, specifies the logical size of the volume. By default, 880 creating a volume establishes a reservation of equal size. For storage 881 pools with a version number of 9 or higher, a refreservation is set 882 instead. Any changes to volsize are reflected in an equivalent change 883 to the reservation (or refreservation). The volsize can only be set to 884 a multiple of volblocksize, and cannot be zero. 885 886 The reservation is kept equal to the volume's logical size to prevent 887 unexpected behavior for consumers. Without the reservation, the volume 888 could run out of space, resulting in undefined behavior or data 889 corruption, depending on how the volume is used. These effects can 890 also occur when the volume size is changed while it is in use 891 (particularly when shrinking the size). Extreme care should be used 892 when adjusting the volume size. 893 894 Though not recommended, a "sparse volume" (also known as "thin 895 provisioned") can be created by specifying the -s option to the zfs 896 create -V command, or by changing the value of the refreservation 897 property (or reservation property on pool version 8 or earlier) after 898 the volume has been created. A "sparse volume" is a volume where the 899 value of refreservation is less than the size of the volume plus the 900 space required to store its metadata. Consequently, writes to a sparse 901 volume can fail with ENOSPC when the pool is low on space. For a 902 sparse volume, changes to volsize are not reflected in the 903 refreservation. A volume that is not sparse is said to be "thick 904 provisioned". A sparse volume can become thick provisioned by setting 905 refreservation to auto. 906 907 vscan=on|off 908 Controls whether regular files should be scanned for viruses when a 909 file is opened and closed. In addition to enabling this property, the 910 virus scan service must also be enabled for virus scanning to occur. 911 The default value is off. 912 913 xattr=on|off 914 Controls whether extended attributes are enabled for this file system. 915 The default value is on. 916 917 zoned=on|off 918 Controls whether the dataset is managed from a non-global zone. See 919 the Zones section for more information. The default value is off. 920 921 The following three properties cannot be changed after the file system is 922 created, and therefore, should be set when the file system is created. 923 If the properties are not set with the zfs create or zpool create 924 commands, these properties are inherited from the parent dataset. If the 925 parent dataset lacks these properties due to having been created prior to 926 these features being supported, the new file system will have the default 927 values for these properties. 928 929 casesensitivity=sensitive|insensitive|mixed 930 Indicates whether the file name matching algorithm used by the file 931 system should be case-sensitive, case-insensitive, or allow a 932 combination of both styles of matching. The default value for the 933 casesensitivity property is sensitive. Traditionally, UNIX and POSIX 934 file systems have case-sensitive file names. 935 936 The mixed value for the casesensitivity property indicates that the 937 file system can support requests for both case-sensitive and case- 938 insensitive matching behavior. Currently, case-insensitive matching 939 behavior on a file system that supports mixed behavior is limited to 940 the SMB server product. For more information about the mixed value 941 behavior, see the "ZFS Administration Guide". 942 943 normalization=none|formC|formD|formKC|formKD 944 Indicates whether the file system should perform a unicode 945 normalization of file names whenever two file names are compared, and 946 which normalization algorithm should be used. File names are always 947 stored unmodified, names are normalized as part of any comparison 948 process. If this property is set to a legal value other than none, and 949 the utf8only property was left unspecified, the utf8only property is 950 automatically set to on. The default value of the normalization 951 property is none. This property cannot be changed after the file 952 system is created. 953 954 utf8only=on|off 955 Indicates whether the file system should reject file names that include 956 characters that are not present in the UTF-8 character code set. If 957 this property is explicitly set to off, the normalization property must 958 either not be explicitly set or be set to none. The default value for 959 the utf8only property is off. This property cannot be changed after 960 the file system is created. 961 962 The casesensitivity, normalization, and utf8only properties are also new 963 permissions that can be assigned to non-privileged users by using the ZFS 964 delegated administration feature. 965 966 Temporary Mount Point Properties 967 When a file system is mounted, either through mount(1M) for legacy mounts 968 or the zfs mount command for normal file systems, its mount options are 969 set according to its properties. The correlation between properties and 970 mount options is as follows: 971 972 PROPERTY MOUNT OPTION 973 devices devices/nodevices 974 exec exec/noexec 975 readonly ro/rw 976 setuid setuid/nosetuid 977 xattr xattr/noxattr 978 979 In addition, these options can be set on a per-mount basis using the -o 980 option, without affecting the property that is stored on disk. The 981 values specified on the command line override the values stored in the 982 dataset. The nosuid option is an alias for nodevices,nosetuid. These 983 properties are reported as "temporary" by the zfs get command. If the 984 properties are changed while the dataset is mounted, the new setting 985 overrides any temporary settings. 986 987 User Properties 988 In addition to the standard native properties, ZFS supports arbitrary 989 user properties. User properties have no effect on ZFS behavior, but 990 applications or administrators can use them to annotate datasets (file 991 systems, volumes, and snapshots). 992 993 User property names must contain a colon (":") character to distinguish 994 them from native properties. They may contain lowercase letters, 995 numbers, and the following punctuation characters: colon (":"), dash 996 ("-"), period ("."), and underscore ("_"). The expected convention is 997 that the property name is divided into two portions such as 998 module:property, but this namespace is not enforced by ZFS. User 999 property names can be at most 256 characters, and cannot begin with a 1000 dash ("-"). 1001 1002 When making programmatic use of user properties, it is strongly suggested 1003 to use a reversed DNS domain name for the module component of property 1004 names to reduce the chance that two independently-developed packages use 1005 the same property name for different purposes. 1006 1007 The values of user properties are arbitrary strings, are always 1008 inherited, and are never validated. All of the commands that operate on 1009 properties (zfs list, zfs get, zfs set, and so forth) can be used to 1010 manipulate both native properties and user properties. Use the zfs 1011 inherit command to clear a user property. If the property is not defined 1012 in any parent dataset, it is removed entirely. Property values are 1013 limited to 8192 bytes. 1014 1015 ZFS Volumes as Swap or Dump Devices 1016 During an initial installation a swap device and dump device are created 1017 on ZFS volumes in the ZFS root pool. By default, the swap area size is 1018 based on 1/2 the size of physical memory up to 2 Gbytes. The size of the 1019 dump device depends on the kernel's requirements at installation time. 1020 Separate ZFS volumes must be used for the swap area and dump devices. Do 1021 not swap to a file on a ZFS file system. A ZFS swap file configuration 1022 is not supported. 1023 1024 If you need to change your swap area or dump device after the system is 1025 installed or upgraded, use the swap(1M) and dumpadm(1M) commands. 1026 1027 SUBCOMMANDS 1028 All subcommands that modify state are logged persistently to the pool in 1029 their original form. 1030 1031 zfs -? 1032 Displays a help message. 1033 1034 zfs create [-p] [-o property=value]... filesystem 1035 Creates a new ZFS file system. The file system is automatically 1036 mounted according to the mountpoint property inherited from the parent. 1037 1038 -o property=value 1039 Sets the specified property as if the command zfs set 1040 property=value was invoked at the same time the dataset was 1041 created. Any editable ZFS property can also be set at creation 1042 time. Multiple -o options can be specified. An error results if 1043 the same property is specified in multiple -o options. 1044 1045 -p Creates all the non-existing parent datasets. Datasets created in 1046 this manner are automatically mounted according to the mountpoint 1047 property inherited from their parent. Any property specified on 1048 the command line using the -o option is ignored. If the target 1049 filesystem already exists, the operation completes successfully. 1050 1051 zfs create [-ps] [-b blocksize] [-o property=value]... -V size volume 1052 Creates a volume of the given size. The volume is exported as a block 1053 device in /dev/zvol/{dsk,rdsk}/path, where path is the name of the 1054 volume in the ZFS namespace. The size represents the logical size as 1055 exported by the device. By default, a reservation of equal size is 1056 created. 1057 1058 size is automatically rounded up to the nearest 128 Kbytes to ensure 1059 that the volume has an integral number of blocks regardless of 1060 blocksize. 1061 1062 -b blocksize 1063 Equivalent to -o volblocksize=blocksize. If this option is 1064 specified in conjunction with -o volblocksize, the resulting 1065 behavior is undefined. 1066 1067 -o property=value 1068 Sets the specified property as if the zfs set property=value 1069 command was invoked at the same time the dataset was created. Any 1070 editable ZFS property can also be set at creation time. Multiple 1071 -o options can be specified. An error results if the same property 1072 is specified in multiple -o options. 1073 1074 -p Creates all the non-existing parent datasets. Datasets created in 1075 this manner are automatically mounted according to the mountpoint 1076 property inherited from their parent. Any property specified on 1077 the command line using the -o option is ignored. If the target 1078 filesystem already exists, the operation completes successfully. 1079 1080 -s Creates a sparse volume with no reservation. See volsize in the 1081 Native Properties section for more information about sparse 1082 volumes. 1083 1084 zfs destroy [-Rfnprv] filesystem|volume 1085 Destroys the given dataset. By default, the command unshares any file 1086 systems that are currently shared, unmounts any file systems that are 1087 currently mounted, and refuses to destroy a dataset that has active 1088 dependents (children or clones). 1089 1090 -R Recursively destroy all dependents, including cloned file systems 1091 outside the target hierarchy. 1092 1093 -f Force an unmount of any file systems using the unmount -f command. 1094 This option has no effect on non-file systems or unmounted file 1095 systems. 1096 1097 -n Do a dry-run ("No-op") deletion. No data will be deleted. This is 1098 useful in conjunction with the -v or -p flags to determine what 1099 data would be deleted. 1100 1101 -p Print machine-parsable verbose information about the deleted data. 1102 1103 -r Recursively destroy all children. 1104 1105 -v Print verbose information about the deleted data. 1106 1107 Extreme care should be taken when applying either the -r or the -R 1108 options, as they can destroy large portions of a pool and cause 1109 unexpected behavior for mounted file systems in use. 1110 1111 zfs destroy [-Rdnprv] filesystem|volume@snap[%snap[,snap[%snap]]]... 1112 The given snapshots are destroyed immediately if and only if the zfs 1113 destroy command without the -d option would have destroyed it. Such 1114 immediate destruction would occur, for example, if the snapshot had no 1115 clones and the user-initiated reference count were zero. 1116 1117 If a snapshot does not qualify for immediate destruction, it is marked 1118 for deferred deletion. In this state, it exists as a usable, visible 1119 snapshot until both of the preconditions listed above are met, at which 1120 point it is destroyed. 1121 1122 An inclusive range of snapshots may be specified by separating the 1123 first and last snapshots with a percent sign. The first and/or last 1124 snapshots may be left blank, in which case the filesystem's oldest or 1125 newest snapshot will be implied. 1126 1127 Multiple snapshots (or ranges of snapshots) of the same filesystem or 1128 volume may be specified in a comma-separated list of snapshots. Only 1129 the snapshot's short name (the part after the @) should be specified 1130 when using a range or comma-separated list to identify multiple 1131 snapshots. 1132 1133 -R Recursively destroy all clones of these snapshots, including the 1134 clones, snapshots, and children. If this flag is specified, the -d 1135 flag will have no effect. 1136 1137 -d Defer snapshot deletion. 1138 1139 -n Do a dry-run ("No-op") deletion. No data will be deleted. This is 1140 useful in conjunction with the -p or -v flags to determine what 1141 data would be deleted. 1142 1143 -p Print machine-parsable verbose information about the deleted data. 1144 1145 -r Destroy (or mark for deferred deletion) all snapshots with this 1146 name in descendent file systems. 1147 1148 -v Print verbose information about the deleted data. 1149 1150 Extreme care should be taken when applying either the -r or the -R 1151 options, as they can destroy large portions of a pool and cause 1152 unexpected behavior for mounted file systems in use. 1153 1154 zfs destroy filesystem|volume#bookmark 1155 The given bookmark is destroyed. 1156 1157 zfs snapshot [-r] [-o property=value]... 1158 filesystem@snapname|volume@snapname... 1159 Creates snapshots with the given names. All previous modifications by 1160 successful system calls to the file system are part of the snapshots. 1161 Snapshots are taken atomically, so that all snapshots correspond to the 1162 same moment in time. See the Snapshots section for details. 1163 1164 -o property=value 1165 Sets the specified property; see zfs create for details. 1166 1167 -r Recursively create snapshots of all descendent datasets 1168 1169 zfs rollback [-Rfr] snapshot 1170 Roll back the given dataset to a previous snapshot. When a dataset is 1171 rolled back, all data that has changed since the snapshot is discarded, 1172 and the dataset reverts to the state at the time of the snapshot. By 1173 default, the command refuses to roll back to a snapshot other than the 1174 most recent one. In order to do so, all intermediate snapshots and 1175 bookmarks must be destroyed by specifying the -r option. 1176 1177 The -rR options do not recursively destroy the child snapshots of a 1178 recursive snapshot. Only direct snapshots of the specified filesystem 1179 are destroyed by either of these options. To completely roll back a 1180 recursive snapshot, you must rollback the individual child snapshots. 1181 1182 -R Destroy any more recent snapshots and bookmarks, as well as any 1183 clones of those snapshots. 1184 1185 -f Used with the -R option to force an unmount of any clone file 1186 systems that are to be destroyed. 1187 1188 -r Destroy any snapshots and bookmarks more recent than the one 1189 specified. 1190 1191 zfs clone [-p] [-o property=value]... snapshot filesystem|volume 1192 Creates a clone of the given snapshot. See the Clones section for 1193 details. The target dataset can be located anywhere in the ZFS 1194 hierarchy, and is created as the same type as the original. 1195 1196 -o property=value 1197 Sets the specified property; see zfs create for details. 1198 1199 -p Creates all the non-existing parent datasets. Datasets created in 1200 this manner are automatically mounted according to the mountpoint 1201 property inherited from their parent. If the target filesystem or 1202 volume already exists, the operation completes successfully. 1203 1204 zfs promote clone-filesystem 1205 Promotes a clone file system to no longer be dependent on its "origin" 1206 snapshot. This makes it possible to destroy the file system that the 1207 clone was created from. The clone parent-child dependency relationship 1208 is reversed, so that the origin file system becomes a clone of the 1209 specified file system. 1210 1211 The snapshot that was cloned, and any snapshots previous to this 1212 snapshot, are now owned by the promoted clone. The space they use 1213 moves from the origin file system to the promoted clone, so enough 1214 space must be available to accommodate these snapshots. No new space 1215 is consumed by this operation, but the space accounting is adjusted. 1216 The promoted clone must not have any conflicting snapshot names of its 1217 own. The rename subcommand can be used to rename any conflicting 1218 snapshots. 1219 1220 zfs rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot 1221 1222 zfs rename [-fp] filesystem|volume filesystem|volume 1223 Renames the given dataset. The new target can be located anywhere in 1224 the ZFS hierarchy, with the exception of snapshots. Snapshots can only 1225 be renamed within the parent file system or volume. When renaming a 1226 snapshot, the parent file system of the snapshot does not need to be 1227 specified as part of the second argument. Renamed file systems can 1228 inherit new mount points, in which case they are unmounted and 1229 remounted at the new mount point. 1230 1231 -f Force unmount any filesystems that need to be unmounted in the 1232 process. 1233 1234 -p Creates all the nonexistent parent datasets. Datasets created in 1235 this manner are automatically mounted according to the mountpoint 1236 property inherited from their parent. 1237 1238 zfs rename -r snapshot snapshot 1239 Recursively rename the snapshots of all descendent datasets. Snapshots 1240 are the only dataset that can be renamed recursively. 1241 1242 zfs list [-r|-d depth] [-Hp] [-o property[,property]...] [-s property]... 1243 [-S property]... [-t type[,type]...] [filesystem|volume|snapshot]... 1244 Lists the property information for the given datasets in tabular form. 1245 If specified, you can list property information by the absolute 1246 pathname or the relative pathname. By default, all file systems and 1247 volumes are displayed. Snapshots are displayed if the listsnaps 1248 property is on (the default is off). The following fields are 1249 displayed, name,used,available,referenced,mountpoint. 1250 1251 -H Used for scripting mode. Do not print headers and separate fields 1252 by a single tab instead of arbitrary white space. 1253 1254 -S property 1255 Same as the -s option, but sorts by property in descending order. 1256 1257 -d depth 1258 Recursively display any children of the dataset, limiting the 1259 recursion to depth. A depth of 1 will display only the dataset and 1260 its direct children. 1261 1262 -o property 1263 A comma-separated list of properties to display. The property must 1264 be: 1265 1266 o One of the properties described in the Native Properties 1267 section 1268 1269 o A user property 1270 1271 o The value name to display the dataset name 1272 1273 o The value space to display space usage properties on file 1274 systems and volumes. This is a shortcut for specifying -o 1275 name,avail,used,usedsnap,usedds,usedrefreserv,usedchild -t 1276 filesystem,volume syntax. 1277 1278 -p Display numbers in parsable (exact) values. 1279 1280 -r Recursively display any children of the dataset on the command 1281 line. 1282 1283 -s property 1284 A property for sorting the output by column in ascending order 1285 based on the value of the property. The property must be one of 1286 the properties described in the Properties section, or the special 1287 value name to sort by the dataset name. Multiple properties can be 1288 specified at one time using multiple -s property options. Multiple 1289 -s options are evaluated from left to right in decreasing order of 1290 importance. The following is a list of sorting criteria: 1291 1292 o Numeric types sort in numeric order. 1293 1294 o String types sort in alphabetical order. 1295 1296 o Types inappropriate for a row sort that row to the literal 1297 bottom, regardless of the specified ordering. 1298 1299 If no sorting options are specified the existing behavior of zfs 1300 list is preserved. 1301 1302 -t type 1303 A comma-separated list of types to display, where type is one of 1304 filesystem, snapshot, volume, bookmark, or all. For example, 1305 specifying -t snapshot displays only snapshots. 1306 1307 zfs set property=value [property=value]... filesystem|volume|snapshot... 1308 Sets the property or list of properties to the given value(s) for each 1309 dataset. Only some properties can be edited. See the Properties 1310 section for more information on what properties can be set and 1311 acceptable values. Numeric values can be specified as exact values, or 1312 in a human-readable form with a suffix of B, K, M, G, T, P, E, Z (for 1313 bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, 1314 or zettabytes, respectively). User properties can be set on snapshots. 1315 For more information, see the User Properties section. 1316 1317 zfs get [-r|-d depth] [-Hp] [-o field[,field]...] [-s source[,source]...] 1318 [-t type[,type]...] all | property[,property]... 1319 filesystem|volume|snapshot|bookmark... 1320 Displays properties for the given datasets. If no datasets are 1321 specified, then the command displays properties for all datasets on the 1322 system. For each property, the following columns are displayed: 1323 1324 name Dataset name 1325 property Property name 1326 value Property value 1327 source Property source. Can either be local, default, 1328 temporary, inherited, or none (-). 1329 1330 All columns are displayed by default, though this can be controlled by 1331 using the -o option. This command takes a comma-separated list of 1332 properties as described in the Native Properties and User Properties 1333 sections. 1334 1335 The special value all can be used to display all properties that apply 1336 to the given dataset's type (filesystem, volume, snapshot, or 1337 bookmark). 1338 1339 -H Display output in a form more easily parsed by scripts. Any 1340 headers are omitted, and fields are explicitly separated by a 1341 single tab instead of an arbitrary amount of space. 1342 1343 -d depth 1344 Recursively display any children of the dataset, limiting the 1345 recursion to depth. A depth of 1 will display only the dataset and 1346 its direct children. 1347 1348 -o field 1349 A comma-separated list of columns to display. 1350 name,property,value,source is the default value. 1351 1352 -p Display numbers in parsable (exact) values. 1353 1354 -r Recursively display properties for any children. 1355 1356 -s source 1357 A comma-separated list of sources to display. Those properties 1358 coming from a source other than those in this list are ignored. 1359 Each source must be one of the following: local, default, 1360 inherited, temporary, and none. The default value is all sources. 1361 1362 -t type 1363 A comma-separated list of types to display, where type is one of 1364 filesystem, snapshot, volume, bookmark, or all. 1365 1366 zfs inherit [-rS] property filesystem|volume|snapshot... 1367 Clears the specified property, causing it to be inherited from an 1368 ancestor, restored to default if no ancestor has the property set, or 1369 with the -S option reverted to the received value if one exists. See 1370 the Properties section for a listing of default values, and details on 1371 which properties can be inherited. 1372 1373 -r Recursively inherit the given property for all children. 1374 1375 -S Revert the property to the received value if one exists; otherwise 1376 operate as if the -S option was not specified. 1377 1378 zfs remap filesystem|volume 1379 Remap the indirect blocks in the given fileystem or volume so that they 1380 no longer reference blocks on previously removed vdevs and we can 1381 eventually shrink the size of the indirect mapping objects for the 1382 previously removed vdevs. Note that remapping all blocks might not be 1383 possible and that references from snapshots will still exist and cannot 1384 be remapped. 1385 1386 zfs upgrade 1387 Displays a list of file systems that are not the most recent version. 1388 1389 zfs upgrade -v 1390 Displays a list of currently supported file system versions. 1391 1392 zfs upgrade [-r] [-V version] -a | filesystem 1393 Upgrades file systems to a new on-disk version. Once this is done, the 1394 file systems will no longer be accessible on systems running older 1395 versions of the software. zfs send streams generated from new 1396 snapshots of these file systems cannot be accessed on systems running 1397 older versions of the software. 1398 1399 In general, the file system version is independent of the pool version. 1400 See zpool(1M) for information on the zpool upgrade command. 1401 1402 In some cases, the file system version and the pool version are 1403 interrelated and the pool version must be upgraded before the file 1404 system version can be upgraded. 1405 1406 -V version 1407 Upgrade to the specified version. If the -V flag is not specified, 1408 this command upgrades to the most recent version. This option can 1409 only be used to increase the version number, and only up to the 1410 most recent version supported by this software. 1411 1412 -a Upgrade all file systems on all imported pools. 1413 1414 filesystem 1415 Upgrade the specified file system. 1416 1417 -r Upgrade the specified file system and all descendent file systems. 1418 1419 zfs userspace [-Hinp] [-o field[,field]...] [-s field]... [-S field]... 1420 [-t type[,type]...] filesystem|snapshot 1421 Displays space consumed by, and quotas on, each user in the specified 1422 filesystem or snapshot. This corresponds to the userused@user and 1423 userquota@user properties. 1424 1425 -H Do not print headers, use tab-delimited output. 1426 1427 -S field 1428 Sort by this field in reverse order. See -s. 1429 1430 -i Translate SID to POSIX ID. The POSIX ID may be ephemeral if no 1431 mapping exists. Normal POSIX interfaces (for example, stat(2), ls 1432 -l) perform this translation, so the -i option allows the output 1433 from zfs userspace to be compared directly with those utilities. 1434 However, -i may lead to confusion if some files were created by an 1435 SMB user before a SMB-to-POSIX name mapping was established. In 1436 such a case, some files will be owned by the SMB entity and some by 1437 the POSIX entity. However, the -i option will report that the 1438 POSIX entity has the total usage and quota for both. 1439 1440 -n Print numeric ID instead of user/group name. 1441 1442 -o field[,field]... 1443 Display only the specified fields from the following set: type, 1444 name, used, quota. The default is to display all fields. 1445 1446 -p Use exact (parsable) numeric output. 1447 1448 -s field 1449 Sort output by this field. The -s and -S flags may be specified 1450 multiple times to sort first by one field, then by another. The 1451 default is -s type -s name. 1452 1453 -t type[,type]... 1454 Print only the specified types from the following set: all, 1455 posixuser, smbuser, posixgroup, smbgroup. The default is -t 1456 posixuser,smbuser. The default can be changed to include group 1457 types. 1458 1459 zfs groupspace [-Hinp] [-o field[,field]...] [-s field]... [-S field]... 1460 [-t type[,type]...] filesystem|snapshot 1461 Displays space consumed by, and quotas on, each group in the specified 1462 filesystem or snapshot. This subcommand is identical to zfs userspace, 1463 except that the default types to display are -t posixgroup,smbgroup. 1464 1465 zfs mount 1466 Displays all ZFS file systems currently mounted. 1467 1468 zfs mount [-Ov] [-o options] -a | filesystem 1469 Mounts ZFS file systems. 1470 1471 -O Perform an overlay mount. See mount(1M) for more information. 1472 1473 -a Mount all available ZFS file systems. Invoked automatically as 1474 part of the boot process. 1475 1476 filesystem 1477 Mount the specified filesystem. 1478 1479 -o options 1480 An optional, comma-separated list of mount options to use 1481 temporarily for the duration of the mount. See the Temporary Mount 1482 Point Properties section for details. 1483 1484 -v Report mount progress. 1485 1486 zfs unmount [-f] -a | filesystem|mountpoint 1487 Unmounts currently mounted ZFS file systems. 1488 1489 -a Unmount all available ZFS file systems. Invoked automatically as 1490 part of the shutdown process. 1491 1492 filesystem|mountpoint 1493 Unmount the specified filesystem. The command can also be given a 1494 path to a ZFS file system mount point on the system. 1495 1496 -f Forcefully unmount the file system, even if it is currently in use. 1497 1498 zfs share -a | filesystem 1499 Shares available ZFS file systems. 1500 1501 -a Share all available ZFS file systems. Invoked automatically as 1502 part of the boot process. 1503 1504 filesystem 1505 Share the specified filesystem according to the sharenfs and 1506 sharesmb properties. File systems are shared when the sharenfs or 1507 sharesmb property is set. 1508 1509 zfs unshare -a | filesystem|mountpoint 1510 Unshares currently shared ZFS file systems. 1511 1512 -a Unshare all available ZFS file systems. Invoked automatically as 1513 part of the shutdown process. 1514 1515 filesystem|mountpoint 1516 Unshare the specified filesystem. The command can also be given a 1517 path to a ZFS file system shared on the system. 1518 1519 zfs bookmark snapshot bookmark 1520 Creates a bookmark of the given snapshot. Bookmarks mark the point in 1521 time when the snapshot was created, and can be used as the incremental 1522 source for a zfs send command. 1523 1524 This feature must be enabled to be used. See zpool-features(5) for 1525 details on ZFS feature flags and the bookmarks feature. 1526 1527 zfs send [-DLPRcenpv] [[-I|-i] snapshot] snapshot 1528 Creates a stream representation of the second snapshot, which is 1529 written to standard output. The output can be redirected to a file or 1530 to a different system (for example, using ssh(1)). By default, a full 1531 stream is generated. 1532 1533 -D, --dedup 1534 Generate a deduplicated stream. Blocks which would have been sent 1535 multiple times in the send stream will only be sent once. The 1536 receiving system must also support this feature to receive a 1537 deduplicated stream. This flag can be used regardless of the 1538 dataset's dedup property, but performance will be much better if 1539 the filesystem uses a dedup-capable checksum (for example, sha256). 1540 1541 -I snapshot 1542 Generate a stream package that sends all intermediary snapshots 1543 from the first snapshot to the second snapshot. For example, -I @a 1544 fs@d is similar to -i @a fs@b; -i @b fs@c; -i @c fs@d. The 1545 incremental source may be specified as with the -i option. 1546 1547 -L, --large-block 1548 Generate a stream which may contain blocks larger than 128KB. This 1549 flag has no effect if the large_blocks pool feature is disabled, or 1550 if the recordsize property of this filesystem has never been set 1551 above 128KB. The receiving system must have the large_blocks pool 1552 feature enabled as well. See zpool-features(5) for details on ZFS 1553 feature flags and the large_blocks feature. 1554 1555 -P, --parsable 1556 Print machine-parsable verbose information about the stream package 1557 generated. 1558 1559 -R, --replicate 1560 Generate a replication stream package, which will replicate the 1561 specified file system, and all descendent file systems, up to the 1562 named snapshot. When received, all properties, snapshots, 1563 descendent file systems, and clones are preserved. 1564 1565 If the -i or -I flags are used in conjunction with the -R flag, an 1566 incremental replication stream is generated. The current values of 1567 properties, and current snapshot and file system names are set when 1568 the stream is received. If the -F flag is specified when this 1569 stream is received, snapshots and file systems that do not exist on 1570 the sending side are destroyed. 1571 1572 -e, --embed 1573 Generate a more compact stream by using WRITE_EMBEDDED records for 1574 blocks which are stored more compactly on disk by the embedded_data 1575 pool feature. This flag has no effect if the embedded_data feature 1576 is disabled. The receiving system must have the embedded_data 1577 feature enabled. If the lz4_compress feature is active on the 1578 sending system, then the receiving system must have that feature 1579 enabled as well. See zpool-features(5) for details on ZFS feature 1580 flags and the embedded_data feature. 1581 1582 -c, --compressed 1583 Generate a more compact stream by using compressed WRITE records 1584 for blocks which are compressed on disk and in memory (see the 1585 compression property for details). If the lz4_compress feature is 1586 active on the sending system, then the receiving system must have 1587 that feature enabled as well. If the large_blocks feature is 1588 enabled on the sending system but the -L option is not supplied in 1589 conjunction with -c, then the data will be decompressed before 1590 sending so it can be split into smaller block sizes. 1591 1592 -i snapshot 1593 Generate an incremental stream from the first snapshot (the 1594 incremental source) to the second snapshot (the incremental 1595 target). The incremental source can be specified as the last 1596 component of the snapshot name (the @ character and following) and 1597 it is assumed to be from the same file system as the incremental 1598 target. 1599 1600 If the destination is a clone, the source may be the origin 1601 snapshot, which must be fully specified (for example, 1602 pool/fs@origin, not just @origin). 1603 1604 -n, --dryrun 1605 Do a dry-run ("No-op") send. Do not generate any actual send data. 1606 This is useful in conjunction with the -v or -P flags to determine 1607 what data will be sent. In this case, the verbose output will be 1608 written to standard output (contrast with a non-dry-run, where the 1609 stream is written to standard output and the verbose output goes to 1610 standard error). 1611 1612 -p, --props 1613 Include the dataset's properties in the stream. This flag is 1614 implicit when -R is specified. The receiving system must also 1615 support this feature. 1616 1617 -v, --verbose 1618 Print verbose information about the stream package generated. This 1619 information includes a per-second report of how much data has been 1620 sent. 1621 1622 The format of the stream is committed. You will be able to receive 1623 your streams on future versions of ZFS . 1624 1625 zfs send [-Lce] [-i snapshot|bookmark] filesystem|volume|snapshot 1626 Generate a send stream, which may be of a filesystem, and may be 1627 incremental from a bookmark. If the destination is a filesystem or 1628 volume, the pool must be read-only, or the filesystem must not be 1629 mounted. When the stream generated from a filesystem or volume is 1630 received, the default snapshot name will be "--head--". 1631 1632 -L, --large-block 1633 Generate a stream which may contain blocks larger than 128KB. This 1634 flag has no effect if the large_blocks pool feature is disabled, or 1635 if the recordsize property of this filesystem has never been set 1636 above 128KB. The receiving system must have the large_blocks pool 1637 feature enabled as well. See zpool-features(5) for details on ZFS 1638 feature flags and the large_blocks feature. 1639 1640 -c, --compressed 1641 Generate a more compact stream by using compressed WRITE records 1642 for blocks which are compressed on disk and in memory (see the 1643 compression property for details). If the lz4_compress feature is 1644 active on the sending system, then the receiving system must have 1645 that feature enabled as well. If the large_blocks feature is 1646 enabled on the sending system but the -L option is not supplied in 1647 conjunction with -c, then the data will be decompressed before 1648 sending so it can be split into smaller block sizes. 1649 1650 -e, --embed 1651 Generate a more compact stream by using WRITE_EMBEDDED records for 1652 blocks which are stored more compactly on disk by the embedded_data 1653 pool feature. This flag has no effect if the embedded_data feature 1654 is disabled. The receiving system must have the embedded_data 1655 feature enabled. If the lz4_compress feature is active on the 1656 sending system, then the receiving system must have that feature 1657 enabled as well. See zpool-features(5) for details on ZFS feature 1658 flags and the embedded_data feature. 1659 1660 -i snapshot|bookmark 1661 Generate an incremental send stream. The incremental source must 1662 be an earlier snapshot in the destination's history. It will 1663 commonly be an earlier snapshot in the destination's file system, 1664 in which case it can be specified as the last component of the name 1665 (the # or @ character and following). 1666 1667 If the incremental target is a clone, the incremental source can be 1668 the origin snapshot, or an earlier snapshot in the origin's 1669 filesystem, or the origin's origin, etc. 1670 1671 zfs send [-Penv] -t receive_resume_token 1672 Creates a send stream which resumes an interrupted receive. The 1673 receive_resume_token is the value of this property on the filesystem or 1674 volume that was being received into. See the documentation for zfs 1675 receive -s for more details. 1676 1677 zfs receive [-Fnsuv] [-o origin=snapshot] filesystem|volume|snapshot 1678 1679 zfs receive [-Fnsuv] [-d|-e] [-o origin=snapshot] filesystem 1680 Creates a snapshot whose contents are as specified in the stream 1681 provided on standard input. If a full stream is received, then a new 1682 file system is created as well. Streams are created using the zfs send 1683 subcommand, which by default creates a full stream. zfs recv can be 1684 used as an alias for zfs receive. 1685 1686 If an incremental stream is received, then the destination file system 1687 must already exist, and its most recent snapshot must match the 1688 incremental stream's source. For zvols, the destination device link is 1689 destroyed and recreated, which means the zvol cannot be accessed during 1690 the receive operation. 1691 1692 When a snapshot replication package stream that is generated by using 1693 the zfs send -R command is received, any snapshots that do not exist on 1694 the sending location are destroyed by using the zfs destroy -d command. 1695 1696 The name of the snapshot (and file system, if a full stream is 1697 received) that this subcommand creates depends on the argument type and 1698 the use of the -d or -e options. 1699 1700 If the argument is a snapshot name, the specified snapshot is created. 1701 If the argument is a file system or volume name, a snapshot with the 1702 same name as the sent snapshot is created within the specified 1703 filesystem or volume. If neither of the -d or -e options are 1704 specified, the provided target snapshot name is used exactly as 1705 provided. 1706 1707 The -d and -e options cause the file system name of the target snapshot 1708 to be determined by appending a portion of the sent snapshot's name to 1709 the specified target filesystem. If the -d option is specified, all 1710 but the first element of the sent snapshot's file system path (usually 1711 the pool name) is used and any required intermediate file systems 1712 within the specified one are created. If the -e option is specified, 1713 then only the last element of the sent snapshot's file system name 1714 (i.e. the name of the source file system itself) is used as the target 1715 file system name. 1716 1717 -F Force a rollback of the file system to the most recent snapshot 1718 before performing the receive operation. If receiving an 1719 incremental replication stream (for example, one generated by zfs 1720 send -R [-i|-I]), destroy snapshots and file systems that do not 1721 exist on the sending side. 1722 1723 -d Discard the first element of the sent snapshot's file system name, 1724 using the remaining elements to determine the name of the target 1725 file system for the new snapshot as described in the paragraph 1726 above. 1727 1728 -e Discard all but the last element of the sent snapshot's file system 1729 name, using that element to determine the name of the target file 1730 system for the new snapshot as described in the paragraph above. 1731 1732 -n Do not actually receive the stream. This can be useful in 1733 conjunction with the -v option to verify the name the receive 1734 operation would use. 1735 1736 -o origin=snapshot 1737 Forces the stream to be received as a clone of the given snapshot. 1738 If the stream is a full send stream, this will create the 1739 filesystem described by the stream as a clone of the specified 1740 snapshot. Which snapshot was specified will not affect the success 1741 or failure of the receive, as long as the snapshot does exist. If 1742 the stream is an incremental send stream, all the normal 1743 verification will be performed. 1744 1745 -u File system that is associated with the received stream is not 1746 mounted. 1747 1748 -v Print verbose information about the stream and the time required to 1749 perform the receive operation. 1750 1751 -s If the receive is interrupted, save the partially received state, 1752 rather than deleting it. Interruption may be due to premature 1753 termination of the stream (e.g. due to network failure or failure 1754 of the remote system if the stream is being read over a network 1755 connection), a checksum error in the stream, termination of the zfs 1756 receive process, or unclean shutdown of the system. 1757 1758 The receive can be resumed with a stream generated by zfs send -t 1759 token, where the token is the value of the receive_resume_token 1760 property of the filesystem or volume which is received into. 1761 1762 To use this flag, the storage pool must have the extensible_dataset 1763 feature enabled. See zpool-features(5) for details on ZFS feature 1764 flags. 1765 1766 zfs receive -A filesystem|volume 1767 Abort an interrupted zfs receive -s, deleting its saved partially 1768 received state. 1769 1770 zfs allow filesystem|volume 1771 Displays permissions that have been delegated on the specified 1772 filesystem or volume. See the other forms of zfs allow for more 1773 information. 1774 1775 zfs allow [-dglu] user|group[,user|group]... 1776 perm|@setname[,perm|@setname]... filesystem|volume 1777 1778 zfs allow [-dl] -e|everyone perm|@setname[,perm|@setname]... 1779 filesystem|volume 1780 Delegates ZFS administration permission for the file systems to non- 1781 privileged users. 1782 1783 -d Allow only for the descendent file systems. 1784 1785 -e|everyone 1786 Specifies that the permissions be delegated to everyone. 1787 1788 -g group[,group]... 1789 Explicitly specify that permissions are delegated to the group. 1790 1791 -l Allow "locally" only for the specified file system. 1792 1793 -u user[,user]... 1794 Explicitly specify that permissions are delegated to the user. 1795 1796 user|group[,user|group]... 1797 Specifies to whom the permissions are delegated. Multiple entities 1798 can be specified as a comma-separated list. If neither of the -gu 1799 options are specified, then the argument is interpreted 1800 preferentially as the keyword everyone, then as a user name, and 1801 lastly as a group name. To specify a user or group named 1802 "everyone", use the -g or -u options. To specify a group with the 1803 same name as a user, use the -g options. 1804 1805 perm|@setname[,perm|@setname]... 1806 The permissions to delegate. Multiple permissions may be specified 1807 as a comma-separated list. Permission names are the same as ZFS 1808 subcommand and property names. See the property list below. 1809 Property set names, which begin with @, may be specified. See the 1810 -s form below for details. 1811 1812 If neither of the -dl options are specified, or both are, then the 1813 permissions are allowed for the file system or volume, and all of its 1814 descendents. 1815 1816 Permissions are generally the ability to use a ZFS subcommand or change 1817 a ZFS property. The following permissions are available: 1818 1819 NAME TYPE NOTES 1820 allow subcommand Must also have the permission that is 1821 being allowed 1822 clone subcommand Must also have the 'create' ability and 1823 'mount' ability in the origin file system 1824 create subcommand Must also have the 'mount' ability 1825 destroy subcommand Must also have the 'mount' ability 1826 diff subcommand Allows lookup of paths within a dataset 1827 given an object number, and the ability 1828 to create snapshots necessary to 1829 'zfs diff'. 1830 mount subcommand Allows mount/umount of ZFS datasets 1831 promote subcommand Must also have the 'mount' and 'promote' 1832 ability in the origin file system 1833 receive subcommand Must also have the 'mount' and 'create' 1834 ability 1835 rename subcommand Must also have the 'mount' and 'create' 1836 ability in the new parent 1837 rollback subcommand Must also have the 'mount' ability 1838 send subcommand 1839 share subcommand Allows sharing file systems over NFS 1840 or SMB protocols 1841 snapshot subcommand Must also have the 'mount' ability 1842 1843 groupquota other Allows accessing any groupquota@... 1844 property 1845 groupused other Allows reading any groupused@... property 1846 userprop other Allows changing any user property 1847 userquota other Allows accessing any userquota@... 1848 property 1849 userused other Allows reading any userused@... property 1850 1851 aclinherit property 1852 aclmode property 1853 atime property 1854 canmount property 1855 casesensitivity property 1856 checksum property 1857 compression property 1858 copies property 1859 devices property 1860 exec property 1861 filesystem_limit property 1862 mountpoint property 1863 nbmand property 1864 normalization property 1865 primarycache property 1866 quota property 1867 readonly property 1868 recordsize property 1869 refquota property 1870 refreservation property 1871 reservation property 1872 secondarycache property 1873 setuid property 1874 sharenfs property 1875 sharesmb property 1876 snapdir property 1877 snapshot_limit property 1878 utf8only property 1879 version property 1880 volblocksize property 1881 volsize property 1882 vscan property 1883 xattr property 1884 zoned property 1885 1886 zfs allow -c perm|@setname[,perm|@setname]... filesystem|volume 1887 Sets "create time" permissions. These permissions are granted 1888 (locally) to the creator of any newly-created descendent file system. 1889 1890 zfs allow -s @setname perm|@setname[,perm|@setname]... filesystem|volume 1891 Defines or adds permissions to a permission set. The set can be used 1892 by other zfs allow commands for the specified file system and its 1893 descendents. Sets are evaluated dynamically, so changes to a set are 1894 immediately reflected. Permission sets follow the same naming 1895 restrictions as ZFS file systems, but the name must begin with @, and 1896 can be no more than 64 characters long. 1897 1898 zfs unallow [-dglru] user|group[,user|group]... 1899 [perm|@setname[,perm|@setname]...] filesystem|volume 1900 1901 zfs unallow [-dlr] -e|everyone [perm|@setname[,perm|@setname]...] 1902 filesystem|volume 1903 1904 zfs unallow [-r] -c [perm|@setname[,perm|@setname]...] filesystem|volume 1905 Removes permissions that were granted with the zfs allow command. No 1906 permissions are explicitly denied, so other permissions granted are 1907 still in effect. For example, if the permission is granted by an 1908 ancestor. If no permissions are specified, then all permissions for 1909 the specified user, group, or everyone are removed. Specifying 1910 everyone (or using the -e option) only removes the permissions that 1911 were granted to everyone, not all permissions for every user and group. 1912 See the zfs allow command for a description of the -ldugec options. 1913 1914 -r Recursively remove the permissions from this file system and all 1915 descendents. 1916 1917 zfs unallow [-r] -s @setname [perm|@setname[,perm|@setname]...] 1918 filesystem|volume 1919 Removes permissions from a permission set. If no permissions are 1920 specified, then all permissions are removed, thus removing the set 1921 entirely. 1922 1923 zfs hold [-r] tag snapshot... 1924 Adds a single reference, named with the tag argument, to the specified 1925 snapshot or snapshots. Each snapshot has its own tag namespace, and 1926 tags must be unique within that space. 1927 1928 If a hold exists on a snapshot, attempts to destroy that snapshot by 1929 using the zfs destroy command return EBUSY. 1930 1931 -r Specifies that a hold with the given tag is applied recursively to 1932 the snapshots of all descendent file systems. 1933 1934 zfs holds [-r] snapshot... 1935 Lists all existing user references for the given snapshot or snapshots. 1936 1937 -r Lists the holds that are set on the named descendent snapshots, in 1938 addition to listing the holds on the named snapshot. 1939 1940 zfs release [-r] tag snapshot... 1941 Removes a single reference, named with the tag argument, from the 1942 specified snapshot or snapshots. The tag must already exist for each 1943 snapshot. If a hold exists on a snapshot, attempts to destroy that 1944 snapshot by using the zfs destroy command return EBUSY. 1945 1946 -r Recursively releases a hold with the given tag on the snapshots of 1947 all descendent file systems. 1948 1949 zfs diff [-FHt] snapshot snapshot|filesystem 1950 Display the difference between a snapshot of a given filesystem and 1951 another snapshot of that filesystem from a later time or the current 1952 contents of the filesystem. The first column is a character indicating 1953 the type of change, the other columns indicate pathname, new pathname 1954 (in case of rename), change in link count, and optionally file type 1955 and/or change time. The types of change are: 1956 1957 - The path has been removed 1958 + The path has been created 1959 M The path has been modified 1960 R The path has been renamed 1961 1962 -F Display an indication of the type of file, in a manner similar to 1963 the - option of ls(1). 1964 1965 B Block device 1966 C Character device 1967 / Directory 1968 > Door 1969 | Named pipe 1970 @ Symbolic link 1971 P Event port 1972 = Socket 1973 F Regular file 1974 1975 -H Give more parsable tab-separated output, without header lines and 1976 without arrows. 1977 1978 -t Display the path's inode change time as the first column of output. 1979 1980 zfs program [-n] [-t timeout] [-m memory_limit] pool script [arg1 ...] 1981 Executes script as a ZFS channel program on pool. The ZFS channel 1982 program interface allows ZFS administrative operations to be run 1983 programmatically via a Lua script. The entire script is executed 1984 atomically, with no other administrative operations taking effect 1985 concurrently. A library of ZFS calls is made available to channel 1986 program scripts. Channel programs may only be run with root 1987 privileges. 1988 1989 For full documentation of the ZFS channel program interface, see the 1990 manual page for 1991 1992 -n 1993 Executes a read-only channel program, which runs faster. The program 1994 cannot change on-disk state by calling functions from the zfs.sync 1995 submodule. The program can be used to gather information such as 1996 properties and determining if changes would succeed (zfs.check.*). 1997 Without this flag, all pending changes must be synced to disk before 1998 a channel program can complete. 1999 2000 -t timeout 2001 Execution time limit, in milliseconds. If a channel program executes 2002 for longer than the provided timeout, it will be stopped and an error 2003 will be returned. The default timeout is 1000 ms, and can be set to 2004 a maximum of 10000 ms. 2005 2006 -m memory-limit 2007 Memory limit, in bytes. If a channel program attempts to allocate 2008 more memory than the given limit, it will be stopped and an error 2009 returned. The default memory limit is 10 MB, and can be set to a 2010 maximum of 100 MB. 2011 2012 All remaining argument strings are passed directly to the channel 2013 program as arguments. See zfs-program(1M) for more information. 2014 2015 EXIT STATUS 2016 The zfs utility exits 0 on success, 1 if an error occurs, and 2 if 2017 invalid command line options were specified. 2018 2019 EXAMPLES 2020 Example 1 Creating a ZFS File System Hierarchy 2021 The following commands create a file system named pool/home and a file 2022 system named pool/home/bob. The mount point /export/home is set for 2023 the parent file system, and is automatically inherited by the child 2024 file system. 2025 2026 # zfs create pool/home 2027 # zfs set mountpoint=/export/home pool/home 2028 # zfs create pool/home/bob 2029 2030 Example 2 Creating a ZFS Snapshot 2031 The following command creates a snapshot named yesterday. This 2032 snapshot is mounted on demand in the .zfs/snapshot directory at the 2033 root of the pool/home/bob file system. 2034 2035 # zfs snapshot pool/home/bob@yesterday 2036 2037 Example 3 Creating and Destroying Multiple Snapshots 2038 The following command creates snapshots named yesterday of pool/home 2039 and all of its descendent file systems. Each snapshot is mounted on 2040 demand in the .zfs/snapshot directory at the root of its file system. 2041 The second command destroys the newly created snapshots. 2042 2043 # zfs snapshot -r pool/home@yesterday 2044 # zfs destroy -r pool/home@yesterday 2045 2046 Example 4 Disabling and Enabling File System Compression 2047 The following command disables the compression property for all file 2048 systems under pool/home. The next command explicitly enables 2049 compression for pool/home/anne. 2050 2051 # zfs set compression=off pool/home 2052 # zfs set compression=on pool/home/anne 2053 2054 Example 5 Listing ZFS Datasets 2055 The following command lists all active file systems and volumes in the 2056 system. Snapshots are displayed if the listsnaps property is on. The 2057 default is off. See zpool(1M) for more information on pool properties. 2058 2059 # zfs list 2060 NAME USED AVAIL REFER MOUNTPOINT 2061 pool 450K 457G 18K /pool 2062 pool/home 315K 457G 21K /export/home 2063 pool/home/anne 18K 457G 18K /export/home/anne 2064 pool/home/bob 276K 457G 276K /export/home/bob 2065 2066 Example 6 Setting a Quota on a ZFS File System 2067 The following command sets a quota of 50 Gbytes for pool/home/bob. 2068 2069 # zfs set quota=50G pool/home/bob 2070 2071 Example 7 Listing ZFS Properties 2072 The following command lists all properties for pool/home/bob. 2073 2074 # zfs get all pool/home/bob 2075 NAME PROPERTY VALUE SOURCE 2076 pool/home/bob type filesystem - 2077 pool/home/bob creation Tue Jul 21 15:53 2009 - 2078 pool/home/bob used 21K - 2079 pool/home/bob available 20.0G - 2080 pool/home/bob referenced 21K - 2081 pool/home/bob compressratio 1.00x - 2082 pool/home/bob mounted yes - 2083 pool/home/bob quota 20G local 2084 pool/home/bob reservation none default 2085 pool/home/bob recordsize 128K default 2086 pool/home/bob mountpoint /pool/home/bob default 2087 pool/home/bob sharenfs off default 2088 pool/home/bob checksum on default 2089 pool/home/bob compression on local 2090 pool/home/bob atime on default 2091 pool/home/bob devices on default 2092 pool/home/bob exec on default 2093 pool/home/bob setuid on default 2094 pool/home/bob readonly off default 2095 pool/home/bob zoned off default 2096 pool/home/bob snapdir hidden default 2097 pool/home/bob aclmode discard default 2098 pool/home/bob aclinherit restricted default 2099 pool/home/bob canmount on default 2100 pool/home/bob xattr on default 2101 pool/home/bob copies 1 default 2102 pool/home/bob version 4 - 2103 pool/home/bob utf8only off - 2104 pool/home/bob normalization none - 2105 pool/home/bob casesensitivity sensitive - 2106 pool/home/bob vscan off default 2107 pool/home/bob nbmand off default 2108 pool/home/bob sharesmb off default 2109 pool/home/bob refquota none default 2110 pool/home/bob refreservation none default 2111 pool/home/bob primarycache all default 2112 pool/home/bob secondarycache all default 2113 pool/home/bob usedbysnapshots 0 - 2114 pool/home/bob usedbydataset 21K - 2115 pool/home/bob usedbychildren 0 - 2116 pool/home/bob usedbyrefreservation 0 - 2117 2118 The following command gets a single property value. 2119 2120 # zfs get -H -o value compression pool/home/bob 2121 on 2122 The following command lists all properties with local settings for 2123 pool/home/bob. 2124 2125 # zfs get -r -s local -o name,property,value all pool/home/bob 2126 NAME PROPERTY VALUE 2127 pool/home/bob quota 20G 2128 pool/home/bob compression on 2129 2130 Example 8 Rolling Back a ZFS File System 2131 The following command reverts the contents of pool/home/anne to the 2132 snapshot named yesterday, deleting all intermediate snapshots. 2133 2134 # zfs rollback -r pool/home/anne@yesterday 2135 2136 Example 9 Creating a ZFS Clone 2137 The following command creates a writable file system whose initial 2138 contents are the same as pool/home/bob@yesterday. 2139 2140 # zfs clone pool/home/bob@yesterday pool/clone 2141 2142 Example 10 Promoting a ZFS Clone 2143 The following commands illustrate how to test out changes to a file 2144 system, and then replace the original file system with the changed one, 2145 using clones, clone promotion, and renaming: 2146 2147 # zfs create pool/project/production 2148 populate /pool/project/production with data 2149 # zfs snapshot pool/project/production@today 2150 # zfs clone pool/project/production@today pool/project/beta 2151 make changes to /pool/project/beta and test them 2152 # zfs promote pool/project/beta 2153 # zfs rename pool/project/production pool/project/legacy 2154 # zfs rename pool/project/beta pool/project/production 2155 once the legacy version is no longer needed, it can be destroyed 2156 # zfs destroy pool/project/legacy 2157 2158 Example 11 Inheriting ZFS Properties 2159 The following command causes pool/home/bob and pool/home/anne to 2160 inherit the checksum property from their parent. 2161 2162 # zfs inherit checksum pool/home/bob pool/home/anne 2163 2164 Example 12 Remotely Replicating ZFS Data 2165 The following commands send a full stream and then an incremental 2166 stream to a remote machine, restoring them into poolB/received/fs@a and 2167 poolB/received/fs@b, respectively. poolB must contain the file system 2168 poolB/received, and must not initially contain poolB/received/fs. 2169 2170 # zfs send pool/fs@a | \ 2171 ssh host zfs receive poolB/received/fs@a 2172 # zfs send -i a pool/fs@b | \ 2173 ssh host zfs receive poolB/received/fs 2174 2175 Example 13 Using the zfs receive -d Option 2176 The following command sends a full stream of poolA/fsA/fsB@snap to a 2177 remote machine, receiving it into poolB/received/fsA/fsB@snap. The 2178 fsA/fsB@snap portion of the received snapshot's name is determined from 2179 the name of the sent snapshot. poolB must contain the file system 2180 poolB/received. If poolB/received/fsA does not exist, it is created as 2181 an empty file system. 2182 2183 # zfs send poolA/fsA/fsB@snap | \ 2184 ssh host zfs receive -d poolB/received 2185 2186 Example 14 Setting User Properties 2187 The following example sets the user-defined com.example:department 2188 property for a dataset. 2189 2190 # zfs set com.example:department=12345 tank/accounting 2191 2192 Example 15 Performing a Rolling Snapshot 2193 The following example shows how to maintain a history of snapshots with 2194 a consistent naming scheme. To keep a week's worth of snapshots, the 2195 user destroys the oldest snapshot, renames the remaining snapshots, and 2196 then creates a new snapshot, as follows: 2197 2198 # zfs destroy -r pool/users@7daysago 2199 # zfs rename -r pool/users@6daysago @7daysago 2200 # zfs rename -r pool/users@5daysago @6daysago 2201 # zfs rename -r pool/users@yesterday @5daysago 2202 # zfs rename -r pool/users@yesterday @4daysago 2203 # zfs rename -r pool/users@yesterday @3daysago 2204 # zfs rename -r pool/users@yesterday @2daysago 2205 # zfs rename -r pool/users@today @yesterday 2206 # zfs snapshot -r pool/users@today 2207 2208 Example 16 Setting sharenfs Property Options on a ZFS File System 2209 The following commands show how to set sharenfs property options to 2210 enable rw access for a set of IP addresses and to enable root access 2211 for system neo on the tank/home file system. 2212 2213 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home 2214 2215 If you are using DNS for host name resolution, specify the fully 2216 qualified hostname. 2217 2218 Example 17 Delegating ZFS Administration Permissions on a ZFS Dataset 2219 The following example shows how to set permissions so that user cindys 2220 can create, destroy, mount, and take snapshots on tank/cindys. The 2221 permissions on tank/cindys are also displayed. 2222 2223 # zfs allow cindys create,destroy,mount,snapshot tank/cindys 2224 # zfs allow tank/cindys 2225 ---- Permissions on tank/cindys -------------------------------------- 2226 Local+Descendent permissions: 2227 user cindys create,destroy,mount,snapshot 2228 2229 Because the tank/cindys mount point permission is set to 755 by 2230 default, user cindys will be unable to mount file systems under 2231 tank/cindys. Add an ACE similar to the following syntax to provide 2232 mount point access: 2233 2234 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys 2235 2236 Example 18 Delegating Create Time Permissions on a ZFS Dataset 2237 The following example shows how to grant anyone in the group staff to 2238 create file systems in tank/users. This syntax also allows staff 2239 members to destroy their own file systems, but not destroy anyone 2240 else's file system. The permissions on tank/users are also displayed. 2241 2242 # zfs allow staff create,mount tank/users 2243 # zfs allow -c destroy tank/users 2244 # zfs allow tank/users 2245 ---- Permissions on tank/users --------------------------------------- 2246 Permission sets: 2247 destroy 2248 Local+Descendent permissions: 2249 group staff create,mount 2250 2251 Example 19 Defining and Granting a Permission Set on a ZFS Dataset 2252 The following example shows how to define and grant a permission set on 2253 the tank/users file system. The permissions on tank/users are also 2254 displayed. 2255 2256 # zfs allow -s @pset create,destroy,snapshot,mount tank/users 2257 # zfs allow staff @pset tank/users 2258 # zfs allow tank/users 2259 ---- Permissions on tank/users --------------------------------------- 2260 Permission sets: 2261 @pset create,destroy,mount,snapshot 2262 Local+Descendent permissions: 2263 group staff @pset 2264 2265 Example 20 Delegating Property Permissions on a ZFS Dataset 2266 The following example shows to grant the ability to set quotas and 2267 reservations on the users/home file system. The permissions on 2268 users/home are also displayed. 2269 2270 # zfs allow cindys quota,reservation users/home 2271 # zfs allow users/home 2272 ---- Permissions on users/home --------------------------------------- 2273 Local+Descendent permissions: 2274 user cindys quota,reservation 2275 cindys% zfs set quota=10G users/home/marks 2276 cindys% zfs get quota users/home/marks 2277 NAME PROPERTY VALUE SOURCE 2278 users/home/marks quota 10G local 2279 2280 Example 21 Removing ZFS Delegated Permissions on a ZFS Dataset 2281 The following example shows how to remove the snapshot permission from 2282 the staff group on the tank/users file system. The permissions on 2283 tank/users are also displayed. 2284 2285 # zfs unallow staff snapshot tank/users 2286 # zfs allow tank/users 2287 ---- Permissions on tank/users --------------------------------------- 2288 Permission sets: 2289 @pset create,destroy,mount,snapshot 2290 Local+Descendent permissions: 2291 group staff @pset 2292 2293 Example 22 Showing the differences between a snapshot and a ZFS Dataset 2294 The following example shows how to see what has changed between a prior 2295 snapshot of a ZFS dataset and its current state. The -F option is used 2296 to indicate type information for the files affected. 2297 2298 # zfs diff -F tank/test@before tank/test 2299 M / /tank/test/ 2300 M F /tank/test/linked (+1) 2301 R F /tank/test/oldname -> /tank/test/newname 2302 - F /tank/test/deleted 2303 + F /tank/test/created 2304 M F /tank/test/modified 2305 2306 INTERFACE STABILITY 2307 Committed. 2308 2309 SEE ALSO 2310 gzip(1), ssh(1), mount(1M), share(1M), sharemgr(1M), unshare(1M), 2311 zonecfg(1M), zpool(1M), chmod(2), stat(2), write(2), fsync(3C), 2312 dfstab(4), acl(5), attributes(5) 2313 2314 illumos February 10, 2018 illumos --- EOF ---