1 .\" 2 .\" CDDL HEADER START 3 .\" 4 .\" The contents of this file are subject to the terms of the 5 .\" Common Development and Distribution License (the "License"). 6 .\" You may not use this file except in compliance with the License. 7 .\" 8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 .\" or http://www.opensolaris.org/os/licensing. 10 .\" See the License for the specific language governing permissions 11 .\" and limitations under the License. 12 .\" 13 .\" When distributing Covered Code, include this CDDL HEADER in each 14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 .\" If applicable, add the following below this CDDL HEADER, with the 16 .\" fields enclosed by brackets "[]" replaced with your own identifying 17 .\" information: Portions Copyright [yyyy] [name of copyright owner] 18 .\" 19 .\" CDDL HEADER END 20 .\" 21 .\" 22 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. 23 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org> 24 .\" Copyright (c) 2011, 2016 by Delphix. All rights reserved. 25 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. 26 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved. 27 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved. 28 .\" Copyright (c) 2014 Integros [integros.com] 29 .\" Copyright 2017 Nexenta Systems, Inc. 30 .\" Copyright 2018 Joyent, Inc. 31 .\" 32 .Dd Feb 10, 2018 33 .Dt ZFS 1M 34 .Os 35 .Sh NAME 36 .Nm zfs 37 .Nd configures ZFS file systems 38 .Sh SYNOPSIS 39 .Nm 40 .Op Fl \? 41 .Nm 42 .Cm create 43 .Op Fl p 44 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 45 .Ar filesystem 46 .Nm 47 .Cm create 48 .Op Fl ps 49 .Op Fl b Ar blocksize 50 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 51 .Fl V Ar size Ar volume 52 .Nm 53 .Cm destroy 54 .Op Fl Rfnprv 55 .Ar filesystem Ns | Ns Ar volume 56 .Nm 57 .Cm destroy 58 .Op Fl Rdnprv 59 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns 60 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... 61 .Nm 62 .Cm destroy 63 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark 64 .Nm 65 .Cm snapshot 66 .Op Fl r 67 .Oo Fl o Ar property Ns = Ns value Oc Ns ... 68 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... 69 .Nm 70 .Cm rollback 71 .Op Fl Rfr 72 .Ar snapshot 73 .Nm 74 .Cm clone 75 .Op Fl p 76 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 77 .Ar snapshot Ar filesystem Ns | Ns Ar volume 78 .Nm 79 .Cm promote 80 .Ar clone-filesystem 81 .Nm 82 .Cm rename 83 .Op Fl f 84 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 85 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 86 .Nm 87 .Cm rename 88 .Op Fl fp 89 .Ar filesystem Ns | Ns Ar volume 90 .Ar filesystem Ns | Ns Ar volume 91 .Nm 92 .Cm rename 93 .Fl r 94 .Ar snapshot Ar snapshot 95 .Nm 96 .Cm list 97 .Op Fl r Ns | Ns Fl d Ar depth 98 .Op Fl Hp 99 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc 100 .Oo Fl s Ar property Oc Ns ... 101 .Oo Fl S Ar property Oc Ns ... 102 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 103 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... 104 .Nm 105 .Cm remap 106 .Ar filesystem Ns | Ns Ar volume 107 .Nm 108 .Cm set 109 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... 110 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... 111 .Nm 112 .Cm get 113 .Op Fl r Ns | Ns Fl d Ar depth 114 .Op Fl Hp 115 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 116 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc 117 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 118 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... 119 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... 120 .Nm 121 .Cm inherit 122 .Op Fl rS 123 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... 124 .Nm 125 .Cm upgrade 126 .Nm 127 .Cm upgrade 128 .Fl v 129 .Nm 130 .Cm upgrade 131 .Op Fl r 132 .Op Fl V Ar version 133 .Fl a | Ar filesystem 134 .Nm 135 .Cm userspace 136 .Op Fl Hinp 137 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 138 .Oo Fl s Ar field Oc Ns ... 139 .Oo Fl S Ar field Oc Ns ... 140 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 141 .Ar filesystem Ns | Ns Ar snapshot 142 .Nm 143 .Cm groupspace 144 .Op Fl Hinp 145 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 146 .Oo Fl s Ar field Oc Ns ... 147 .Oo Fl S Ar field Oc Ns ... 148 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 149 .Ar filesystem Ns | Ns Ar snapshot 150 .Nm 151 .Cm mount 152 .Nm 153 .Cm mount 154 .Op Fl Ov 155 .Op Fl o Ar options 156 .Fl a | Ar filesystem 157 .Nm 158 .Cm unmount 159 .Op Fl f 160 .Fl a | Ar filesystem Ns | Ns Ar mountpoint 161 .Nm 162 .Cm share 163 .Fl a | Ar filesystem 164 .Nm 165 .Cm unshare 166 .Fl a | Ar filesystem Ns | Ns Ar mountpoint 167 .Nm 168 .Cm bookmark 169 .Ar snapshot bookmark 170 .Nm 171 .Cm send 172 .Op Fl DLPRcenpv 173 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot 174 .Ar snapshot 175 .Nm 176 .Cm send 177 .Op Fl Lce 178 .Op Fl i Ar snapshot Ns | Ns Ar bookmark 179 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 180 .Nm 181 .Cm send 182 .Op Fl Penv 183 .Fl t Ar receive_resume_token 184 .Nm 185 .Cm receive 186 .Op Fl Fnsuv 187 .Op Fl o Sy origin Ns = Ns Ar snapshot 188 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 189 .Nm 190 .Cm receive 191 .Op Fl Fnsuv 192 .Op Fl d Ns | Ns Fl e 193 .Op Fl o Sy origin Ns = Ns Ar snapshot 194 .Ar filesystem 195 .Nm 196 .Cm receive 197 .Fl A 198 .Ar filesystem Ns | Ns Ar volume 199 .Nm 200 .Cm allow 201 .Ar filesystem Ns | Ns Ar volume 202 .Nm 203 .Cm allow 204 .Op Fl dglu 205 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 206 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 207 .Ar setname Oc Ns ... 208 .Ar filesystem Ns | Ns Ar volume 209 .Nm 210 .Cm allow 211 .Op Fl dl 212 .Fl e Ns | Ns Sy everyone 213 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 214 .Ar setname Oc Ns ... 215 .Ar filesystem Ns | Ns Ar volume 216 .Nm 217 .Cm allow 218 .Fl c 219 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 220 .Ar setname Oc Ns ... 221 .Ar filesystem Ns | Ns Ar volume 222 .Nm 223 .Cm allow 224 .Fl s No @ Ns Ar setname 225 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 226 .Ar setname Oc Ns ... 227 .Ar filesystem Ns | Ns Ar volume 228 .Nm 229 .Cm unallow 230 .Op Fl dglru 231 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 232 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 233 .Ar setname Oc Ns ... Oc 234 .Ar filesystem Ns | Ns Ar volume 235 .Nm 236 .Cm unallow 237 .Op Fl dlr 238 .Fl e Ns | Ns Sy everyone 239 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 240 .Ar setname Oc Ns ... Oc 241 .Ar filesystem Ns | Ns Ar volume 242 .Nm 243 .Cm unallow 244 .Op Fl r 245 .Fl c 246 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 247 .Ar setname Oc Ns ... Oc 248 .Ar filesystem Ns | Ns Ar volume 249 .Nm 250 .Cm unallow 251 .Op Fl r 252 .Fl s @ Ns Ar setname 253 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 254 .Ar setname Oc Ns ... Oc 255 .Ar filesystem Ns | Ns Ar volume 256 .Nm 257 .Cm hold 258 .Op Fl r 259 .Ar tag Ar snapshot Ns ... 260 .Nm 261 .Cm holds 262 .Op Fl r 263 .Ar snapshot Ns ... 264 .Nm 265 .Cm release 266 .Op Fl r 267 .Ar tag Ar snapshot Ns ... 268 .Nm 269 .Cm diff 270 .Op Fl FHt 271 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem 272 .Nm 273 .Cm program 274 .Op Fl n 275 .Op Fl t Ar timeout 276 .Op Fl m Ar memory_limit 277 .Ar pool script 278 .Op Ar arg1 No ... 279 .Sh DESCRIPTION 280 The 281 .Nm 282 command configures ZFS datasets within a ZFS storage pool, as described in 283 .Xr zpool 1M . 284 A dataset is identified by a unique path within the ZFS namespace. 285 For example: 286 .Bd -literal 287 pool/{filesystem,volume,snapshot} 288 .Ed 289 .Pp 290 where the maximum length of a dataset name is 291 .Dv MAXNAMELEN 292 .Pq 256 bytes 293 and the maximum amount of nesting allowed in a path is 50 levels deep. 294 .Pp 295 A dataset can be one of the following: 296 .Bl -tag -width "file system" 297 .It Sy file system 298 A ZFS dataset of type 299 .Sy filesystem 300 can be mounted within the standard system namespace and behaves like other file 301 systems. 302 While ZFS file systems are designed to be POSIX compliant, known issues exist 303 that prevent compliance in some cases. 304 Applications that depend on standards conformance might fail due to non-standard 305 behavior when checking file system free space. 306 .It Sy volume 307 A logical volume exported as a raw or block device. 308 This type of dataset should only be used under special circumstances. 309 File systems are typically used in most environments. 310 .It Sy snapshot 311 A read-only version of a file system or volume at a given point in time. 312 It is specified as 313 .Ar filesystem Ns @ Ns Ar name 314 or 315 .Ar volume Ns @ Ns Ar name . 316 .El 317 .Ss ZFS File System Hierarchy 318 A ZFS storage pool is a logical collection of devices that provide space for 319 datasets. 320 A storage pool is also the root of the ZFS file system hierarchy. 321 .Pp 322 The root of the pool can be accessed as a file system, such as mounting and 323 unmounting, taking snapshots, and setting properties. 324 The physical storage characteristics, however, are managed by the 325 .Xr zpool 1M 326 command. 327 .Pp 328 See 329 .Xr zpool 1M 330 for more information on creating and administering pools. 331 .Ss Snapshots 332 A snapshot is a read-only copy of a file system or volume. 333 Snapshots can be created extremely quickly, and initially consume no additional 334 space within the pool. 335 As data within the active dataset changes, the snapshot consumes more data than 336 would otherwise be shared with the active dataset. 337 .Pp 338 Snapshots can have arbitrary names. 339 Snapshots of volumes can be cloned or rolled back, but cannot be accessed 340 independently. 341 .Pp 342 File system snapshots can be accessed under the 343 .Pa .zfs/snapshot 344 directory in the root of the file system. 345 Snapshots are automatically mounted on demand and may be unmounted at regular 346 intervals. 347 The visibility of the 348 .Pa .zfs 349 directory can be controlled by the 350 .Sy snapdir 351 property. 352 .Ss Clones 353 A clone is a writable volume or file system whose initial contents are the same 354 as another dataset. 355 As with snapshots, creating a clone is nearly instantaneous, and initially 356 consumes no additional space. 357 .Pp 358 Clones can only be created from a snapshot. 359 When a snapshot is cloned, it creates an implicit dependency between the parent 360 and child. 361 Even though the clone is created somewhere else in the dataset hierarchy, the 362 original snapshot cannot be destroyed as long as a clone exists. 363 The 364 .Sy origin 365 property exposes this dependency, and the 366 .Cm destroy 367 command lists any such dependencies, if they exist. 368 .Pp 369 The clone parent-child dependency relationship can be reversed by using the 370 .Cm promote 371 subcommand. 372 This causes the 373 .Qq origin 374 file system to become a clone of the specified file system, which makes it 375 possible to destroy the file system that the clone was created from. 376 .Ss "Mount Points" 377 Creating a ZFS file system is a simple operation, so the number of file systems 378 per system is likely to be numerous. 379 To cope with this, ZFS automatically manages mounting and unmounting file 380 systems without the need to edit the 381 .Pa /etc/vfstab 382 file. 383 All automatically managed file systems are mounted by ZFS at boot time. 384 .Pp 385 By default, file systems are mounted under 386 .Pa /path , 387 where 388 .Ar path 389 is the name of the file system in the ZFS namespace. 390 Directories are created and destroyed as needed. 391 .Pp 392 A file system can also have a mount point set in the 393 .Sy mountpoint 394 property. 395 This directory is created as needed, and ZFS automatically mounts the file 396 system when the 397 .Nm zfs Cm mount Fl a 398 command is invoked 399 .Po without editing 400 .Pa /etc/vfstab 401 .Pc . 402 The 403 .Sy mountpoint 404 property can be inherited, so if 405 .Em pool/home 406 has a mount point of 407 .Pa /export/stuff , 408 then 409 .Em pool/home/user 410 automatically inherits a mount point of 411 .Pa /export/stuff/user . 412 .Pp 413 A file system 414 .Sy mountpoint 415 property of 416 .Sy none 417 prevents the file system from being mounted. 418 .Pp 419 If needed, ZFS file systems can also be managed with traditional tools 420 .Po 421 .Nm mount , 422 .Nm umount , 423 .Pa /etc/vfstab 424 .Pc . 425 If a file system's mount point is set to 426 .Sy legacy , 427 ZFS makes no attempt to manage the file system, and the administrator is 428 responsible for mounting and unmounting the file system. 429 .Ss "Zones" 430 A ZFS file system can be added to a non-global zone by using the 431 .Nm zonecfg Cm add Sy fs 432 subcommand. 433 A ZFS file system that is added to a non-global zone must have its 434 .Sy mountpoint 435 property set to 436 .Sy legacy . 437 .Pp 438 The physical properties of an added file system are controlled by the global 439 administrator. 440 However, the zone administrator can create, modify, or destroy files within the 441 added file system, depending on how the file system is mounted. 442 .Pp 443 A dataset can also be delegated to a non-global zone by using the 444 .Nm zonecfg Cm add Sy dataset 445 subcommand. 446 You cannot delegate a dataset to one zone and the children of the same dataset 447 to another zone. 448 The zone administrator can change properties of the dataset or any of its 449 children. 450 However, the 451 .Sy quota , 452 .Sy filesystem_limit 453 and 454 .Sy snapshot_limit 455 properties of the delegated dataset can be modified only by the global 456 administrator. 457 .Pp 458 A ZFS volume can be added as a device to a non-global zone by using the 459 .Nm zonecfg Cm add Sy device 460 subcommand. 461 However, its physical properties can be modified only by the global 462 administrator. 463 .Pp 464 For more information about 465 .Nm zonecfg 466 syntax, see 467 .Xr zonecfg 1M . 468 .Pp 469 After a dataset is delegated to a non-global zone, the 470 .Sy zoned 471 property is automatically set. 472 A zoned file system cannot be mounted in the global zone, since the zone 473 administrator might have to set the mount point to an unacceptable value. 474 .Pp 475 The global administrator can forcibly clear the 476 .Sy zoned 477 property, though this should be done with extreme care. 478 The global administrator should verify that all the mount points are acceptable 479 before clearing the property. 480 .Ss Native Properties 481 Properties are divided into two types, native properties and user-defined 482 .Po or 483 .Qq user 484 .Pc 485 properties. 486 Native properties either export internal statistics or control ZFS behavior. 487 In addition, native properties are either editable or read-only. 488 User properties have no effect on ZFS behavior, but you can use them to annotate 489 datasets in a way that is meaningful in your environment. 490 For more information about user properties, see the 491 .Sx User Properties 492 section, below. 493 .Pp 494 Every dataset has a set of properties that export statistics about the dataset 495 as well as control various behaviors. 496 Properties are inherited from the parent unless overridden by the child. 497 Some properties apply only to certain types of datasets 498 .Pq file systems, volumes, or snapshots . 499 .Pp 500 The values of numeric properties can be specified using human-readable suffixes 501 .Po for example, 502 .Sy k , 503 .Sy KB , 504 .Sy M , 505 .Sy Gb , 506 and so forth, up to 507 .Sy Z 508 for zettabyte 509 .Pc . 510 The following are all valid 511 .Pq and equal 512 specifications: 513 .Li 1536M, 1.5g, 1.50GB . 514 .Pp 515 The values of non-numeric properties are case sensitive and must be lowercase, 516 except for 517 .Sy mountpoint , 518 .Sy sharenfs , 519 and 520 .Sy sharesmb . 521 .Pp 522 The following native properties consist of read-only statistics about the 523 dataset. 524 These properties can be neither set, nor inherited. 525 Native properties apply to all dataset types unless otherwise noted. 526 .Bl -tag -width "usedbyrefreservation" 527 .It Sy available 528 The amount of space available to the dataset and all its children, assuming that 529 there is no other activity in the pool. 530 Because space is shared within a pool, availability can be limited by any number 531 of factors, including physical pool size, quotas, reservations, or other 532 datasets within the pool. 533 .Pp 534 This property can also be referred to by its shortened column name, 535 .Sy avail . 536 .It Sy compressratio 537 For non-snapshots, the compression ratio achieved for the 538 .Sy used 539 space of this dataset, expressed as a multiplier. 540 The 541 .Sy used 542 property includes descendant datasets, and, for clones, does not include the 543 space shared with the origin snapshot. 544 For snapshots, the 545 .Sy compressratio 546 is the same as the 547 .Sy refcompressratio 548 property. 549 Compression can be turned on by running: 550 .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . 551 The default value is 552 .Sy off . 553 .It Sy createtxg 554 The transaction group (txg) in which the dataset was created. 555 Bookmarks have the same 556 .Sy createtxg 557 as the snapshot they are initially tied to. 558 This property is suitable for ordering a list of snapshots, 559 e.g. for incremental send and receive. 560 .It Sy creation 561 The time this dataset was created. 562 .It Sy clones 563 For snapshots, this property is a comma-separated list of filesystems or volumes 564 which are clones of this snapshot. 565 The clones' 566 .Sy origin 567 property is this snapshot. 568 If the 569 .Sy clones 570 property is not empty, then this snapshot can not be destroyed 571 .Po even with the 572 .Fl r 573 or 574 .Fl f 575 options 576 .Pc . 577 .It Sy defer_destroy 578 This property is 579 .Sy on 580 if the snapshot has been marked for deferred destroy by using the 581 .Nm zfs Cm destroy Fl d 582 command. 583 Otherwise, the property is 584 .Sy off . 585 .It Sy filesystem_count 586 The total number of filesystems and volumes that exist under this location in 587 the dataset tree. 588 This value is only available when a 589 .Sy filesystem_limit 590 has been set somewhere in the tree under which the dataset resides. 591 .It Sy guid 592 The 64 bit GUID of this dataset or bookmark which does not change over its 593 entire lifetime. 594 When a snapshot is sent to another pool, the received snapshot has the same 595 GUID. 596 Thus, the 597 .Sy guid 598 is suitable to identify a snapshot across pools. 599 .It Sy logicalreferenced 600 The amount of space that is 601 .Qq logically 602 accessible by this dataset. 603 See the 604 .Sy referenced 605 property. 606 The logical space ignores the effect of the 607 .Sy compression 608 and 609 .Sy copies 610 properties, giving a quantity closer to the amount of data that applications 611 see. 612 However, it does include space consumed by metadata. 613 .Pp 614 This property can also be referred to by its shortened column name, 615 .Sy lrefer . 616 .It Sy logicalused 617 The amount of space that is 618 .Qq logically 619 consumed by this dataset and all its descendents. 620 See the 621 .Sy used 622 property. 623 The logical space ignores the effect of the 624 .Sy compression 625 and 626 .Sy copies 627 properties, giving a quantity closer to the amount of data that applications 628 see. 629 However, it does include space consumed by metadata. 630 .Pp 631 This property can also be referred to by its shortened column name, 632 .Sy lused . 633 .It Sy mounted 634 For file systems, indicates whether the file system is currently mounted. 635 This property can be either 636 .Sy yes 637 or 638 .Sy no . 639 .It Sy origin 640 For cloned file systems or volumes, the snapshot from which the clone was 641 created. 642 See also the 643 .Sy clones 644 property. 645 .It Sy receive_resume_token 646 For filesystems or volumes which have saved partially-completed state from 647 .Sy zfs receive -s , 648 this opaque token can be provided to 649 .Sy zfs send -t 650 to resume and complete the 651 .Sy zfs receive . 652 .It Sy referenced 653 The amount of data that is accessible by this dataset, which may or may not be 654 shared with other datasets in the pool. 655 When a snapshot or clone is created, it initially references the same amount of 656 space as the file system or snapshot it was created from, since its contents are 657 identical. 658 .Pp 659 This property can also be referred to by its shortened column name, 660 .Sy refer . 661 .It Sy refcompressratio 662 The compression ratio achieved for the 663 .Sy referenced 664 space of this dataset, expressed as a multiplier. 665 See also the 666 .Sy compressratio 667 property. 668 .It Sy snapshot_count 669 The total number of snapshots that exist under this location in the dataset 670 tree. 671 This value is only available when a 672 .Sy snapshot_limit 673 has been set somewhere in the tree under which the dataset resides. 674 .It Sy type 675 The type of dataset: 676 .Sy filesystem , 677 .Sy volume , 678 or 679 .Sy snapshot . 680 .It Sy used 681 The amount of space consumed by this dataset and all its descendents. 682 This is the value that is checked against this dataset's quota and reservation. 683 The space used does not include this dataset's reservation, but does take into 684 account the reservations of any descendent datasets. 685 The amount of space that a dataset consumes from its parent, as well as the 686 amount of space that is freed if this dataset is recursively destroyed, is the 687 greater of its space used and its reservation. 688 .Pp 689 The used space of a snapshot 690 .Po see the 691 .Sx Snapshots 692 section 693 .Pc 694 is space that is referenced exclusively by this snapshot. 695 If this snapshot is destroyed, the amount of 696 .Sy used 697 space will be freed. 698 Space that is shared by multiple snapshots isn't accounted for in this metric. 699 When a snapshot is destroyed, space that was previously shared with this 700 snapshot can become unique to snapshots adjacent to it, thus changing the used 701 space of those snapshots. 702 The used space of the latest snapshot can also be affected by changes in the 703 file system. 704 Note that the 705 .Sy used 706 space of a snapshot is a subset of the 707 .Sy written 708 space of the snapshot. 709 .Pp 710 The amount of space used, available, or referenced does not take into account 711 pending changes. 712 Pending changes are generally accounted for within a few seconds. 713 Committing a change to a disk using 714 .Xr fsync 3C 715 or 716 .Dv O_SYNC 717 does not necessarily guarantee that the space usage information is updated 718 immediately. 719 .It Sy usedby* 720 The 721 .Sy usedby* 722 properties decompose the 723 .Sy used 724 properties into the various reasons that space is used. 725 Specifically, 726 .Sy used No = 727 .Sy usedbychildren No + 728 .Sy usedbydataset No + 729 .Sy usedbyrefreservation No + 730 .Sy usedbysnapshots . 731 These properties are only available for datasets created on 732 .Nm zpool 733 .Qo version 13 Qc 734 pools. 735 .It Sy usedbychildren 736 The amount of space used by children of this dataset, which would be freed if 737 all the dataset's children were destroyed. 738 .It Sy usedbydataset 739 The amount of space used by this dataset itself, which would be freed if the 740 dataset were destroyed 741 .Po after first removing any 742 .Sy refreservation 743 and destroying any necessary snapshots or descendents 744 .Pc . 745 .It Sy usedbyrefreservation 746 The amount of space used by a 747 .Sy refreservation 748 set on this dataset, which would be freed if the 749 .Sy refreservation 750 was removed. 751 .It Sy usedbysnapshots 752 The amount of space consumed by snapshots of this dataset. 753 In particular, it is the amount of space that would be freed if all of this 754 dataset's snapshots were destroyed. 755 Note that this is not simply the sum of the snapshots' 756 .Sy used 757 properties because space can be shared by multiple snapshots. 758 .It Sy userused Ns @ Ns Em user 759 The amount of space consumed by the specified user in this dataset. 760 Space is charged to the owner of each file, as displayed by 761 .Nm ls Fl l . 762 The amount of space charged is displayed by 763 .Nm du 764 and 765 .Nm ls Fl s . 766 See the 767 .Nm zfs Cm userspace 768 subcommand for more information. 769 .Pp 770 Unprivileged users can access only their own space usage. 771 The root user, or a user who has been granted the 772 .Sy userused 773 privilege with 774 .Nm zfs Cm allow , 775 can access everyone's usage. 776 .Pp 777 The 778 .Sy userused Ns @ Ns Em ... 779 properties are not displayed by 780 .Nm zfs Cm get Sy all . 781 The user's name must be appended after the @ symbol, using one of the following 782 forms: 783 .Bl -bullet -width "" 784 .It 785 .Em POSIX name 786 .Po for example, 787 .Sy joe 788 .Pc 789 .It 790 .Em POSIX numeric ID 791 .Po for example, 792 .Sy 789 793 .Pc 794 .It 795 .Em SID name 796 .Po for example, 797 .Sy joe.smith@mydomain 798 .Pc 799 .It 800 .Em SID numeric ID 801 .Po for example, 802 .Sy S-1-123-456-789 803 .Pc 804 .El 805 .It Sy userrefs 806 This property is set to the number of user holds on this snapshot. 807 User holds are set by using the 808 .Nm zfs Cm hold 809 command. 810 .It Sy groupused Ns @ Ns Em group 811 The amount of space consumed by the specified group in this dataset. 812 Space is charged to the group of each file, as displayed by 813 .Nm ls Fl l . 814 See the 815 .Sy userused Ns @ Ns Em user 816 property for more information. 817 .Pp 818 Unprivileged users can only access their own groups' space usage. 819 The root user, or a user who has been granted the 820 .Sy groupused 821 privilege with 822 .Nm zfs Cm allow , 823 can access all groups' usage. 824 .It Sy volblocksize 825 For volumes, specifies the block size of the volume. 826 The 827 .Sy blocksize 828 cannot be changed once the volume has been written, so it should be set at 829 volume creation time. 830 The default 831 .Sy blocksize 832 for volumes is 8 Kbytes. 833 Any power of 2 from 512 bytes to 128 Kbytes is valid. 834 .Pp 835 This property can also be referred to by its shortened column name, 836 .Sy volblock . 837 .It Sy written 838 The amount of space 839 .Sy referenced 840 by this dataset, that was written since the previous snapshot 841 .Pq i.e. that is not referenced by the previous snapshot . 842 .It Sy written Ns @ Ns Em snapshot 843 The amount of 844 .Sy referenced 845 space written to this dataset since the specified snapshot. 846 This is the space that is referenced by this dataset but was not referenced by 847 the specified snapshot. 848 .Pp 849 The 850 .Em snapshot 851 may be specified as a short snapshot name 852 .Po just the part after the 853 .Sy @ 854 .Pc , 855 in which case it will be interpreted as a snapshot in the same filesystem as 856 this dataset. 857 The 858 .Em snapshot 859 may be a full snapshot name 860 .Po Em filesystem Ns @ Ns Em snapshot Pc , 861 which for clones may be a snapshot in the origin's filesystem 862 .Pq or the origin of the origin's filesystem, etc. 863 .El 864 .Pp 865 The following native properties can be used to change the behavior of a ZFS 866 dataset. 867 .Bl -tag -width "" 868 .It Xo 869 .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns 870 .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x 871 .Xc 872 Controls how ACEs are inherited when files and directories are created. 873 .Bl -tag -width "passthrough-x" 874 .It Sy discard 875 does not inherit any ACEs. 876 .It Sy noallow 877 only inherits inheritable ACEs that specify 878 .Qq deny 879 permissions. 880 .It Sy restricted 881 default, removes the 882 .Sy write_acl 883 and 884 .Sy write_owner 885 permissions when the ACE is inherited. 886 .It Sy passthrough 887 inherits all inheritable ACEs without any modifications. 888 .It Sy passthrough-x 889 same meaning as 890 .Sy passthrough , 891 except that the 892 .Sy owner@ , 893 .Sy group@ , 894 and 895 .Sy everyone@ 896 ACEs inherit the execute permission only if the file creation mode also requests 897 the execute bit. 898 .El 899 .Pp 900 When the property value is set to 901 .Sy passthrough , 902 files are created with a mode determined by the inheritable ACEs. 903 If no inheritable ACEs exist that affect the mode, then the mode is set in 904 accordance to the requested mode from the application. 905 .It Xo 906 .Sy aclmode Ns = Ns Sy discard Ns | Ns Sy groupmask Ns | Ns 907 .Sy passthrough Ns | Ns Sy restricted 908 .Xc 909 Controls how an ACL is modified during 910 .Xr chmod 2 911 and how inherited ACEs are modified by the file creation mode. 912 .Bl -tag -width "passthrough" 913 .It Sy discard 914 default, deletes all ACEs except for those representing the mode of the file or 915 directory requested by 916 .Xr chmod 2 . 917 .It Sy groupmask 918 reduces permissions granted by all 919 .Sy ALLOW 920 entries found in the ACL such that they are no greater than the group 921 permissions specified by the mode. 922 .It Sy passthrough 923 indicates that no changes are made to the ACL other than creating or updating 924 the necessary ACEs to represent the new mode of the file or directory. 925 .It Sy restricted 926 causes the 927 .Xr chmod 2 928 operation to return an error when used on any file or directory which has a 929 non-trivial ACL, with entries in addition to those that represent the mode. 930 .El 931 .Pp 932 .Xr chmod 2 933 is required to change the set user ID, set group ID, or sticky bit on a file or 934 directory, as they do not have equivalent ACEs. 935 In order to use 936 .Xr chmod 2 937 on a file or directory with a non-trivial ACL when 938 .Sy aclmode 939 is set to 940 .Sy restricted , 941 you must first remove all ACEs except for those that represent the current mode. 942 .It Sy atime Ns = Ns Sy on Ns | Ns Sy off 943 Controls whether the access time for files is updated when they are read. 944 Turning this property off avoids producing write traffic when reading files and 945 can result in significant performance gains, though it might confuse mailers 946 and other similar utilities. 947 The default value is 948 .Sy on . 949 .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto 950 If this property is set to 951 .Sy off , 952 the file system cannot be mounted, and is ignored by 953 .Nm zfs Cm mount Fl a . 954 Setting this property to 955 .Sy off 956 is similar to setting the 957 .Sy mountpoint 958 property to 959 .Sy none , 960 except that the dataset still has a normal 961 .Sy mountpoint 962 property, which can be inherited. 963 Setting this property to 964 .Sy off 965 allows datasets to be used solely as a mechanism to inherit properties. 966 One example of setting 967 .Sy canmount Ns = Ns Sy off 968 is to have two datasets with the same 969 .Sy mountpoint , 970 so that the children of both datasets appear in the same directory, but might 971 have different inherited characteristics. 972 .Pp 973 When set to 974 .Sy noauto , 975 a dataset can only be mounted and unmounted explicitly. 976 The dataset is not mounted automatically when the dataset is created or 977 imported, nor is it mounted by the 978 .Nm zfs Cm mount Fl a 979 command or unmounted by the 980 .Nm zfs Cm unmount Fl a 981 command. 982 .Pp 983 This property is not inherited. 984 .It Xo 985 .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns 986 .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns 987 .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr 988 .Xc 989 Controls the checksum used to verify data integrity. 990 The default value is 991 .Sy on , 992 which automatically selects an appropriate algorithm 993 .Po currently, 994 .Sy fletcher4 , 995 but this may change in future releases 996 .Pc . 997 The value 998 .Sy off 999 disables integrity checking on user data. 1000 The value 1001 .Sy noparity 1002 not only disables integrity but also disables maintaining parity for user data. 1003 This setting is used internally by a dump device residing on a RAID-Z pool and 1004 should not be used by any other dataset. 1005 Disabling checksums is 1006 .Sy NOT 1007 a recommended practice. 1008 .Pp 1009 The 1010 .Sy sha512 , 1011 .Sy skein , 1012 and 1013 .Sy edonr 1014 checksum algorithms require enabling the appropriate features on the pool. 1015 Please see 1016 .Xr zpool-features 5 1017 for more information on these algorithms. 1018 .Pp 1019 Changing this property affects only newly-written data. 1020 .It Xo 1021 .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns 1022 .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle 1023 .Xc 1024 Controls the compression algorithm used for this dataset. 1025 .Pp 1026 Setting compression to 1027 .Sy on 1028 indicates that the current default compression algorithm should be used. 1029 The default balances compression and decompression speed, with compression ratio 1030 and is expected to work well on a wide variety of workloads. 1031 Unlike all other settings for this property, 1032 .Sy on 1033 does not select a fixed compression type. 1034 As new compression algorithms are added to ZFS and enabled on a pool, the 1035 default compression algorithm may change. 1036 The current default compression algorithm is either 1037 .Sy lzjb 1038 or, if the 1039 .Sy lz4_compress 1040 feature is enabled, 1041 .Sy lz4 . 1042 .Pp 1043 The 1044 .Sy lz4 1045 compression algorithm is a high-performance replacement for the 1046 .Sy lzjb 1047 algorithm. 1048 It features significantly faster compression and decompression, as well as a 1049 moderately higher compression ratio than 1050 .Sy lzjb , 1051 but can only be used on pools with the 1052 .Sy lz4_compress 1053 feature set to 1054 .Sy enabled . 1055 See 1056 .Xr zpool-features 5 1057 for details on ZFS feature flags and the 1058 .Sy lz4_compress 1059 feature. 1060 .Pp 1061 The 1062 .Sy lzjb 1063 compression algorithm is optimized for performance while providing decent data 1064 compression. 1065 .Pp 1066 The 1067 .Sy gzip 1068 compression algorithm uses the same compression as the 1069 .Xr gzip 1 1070 command. 1071 You can specify the 1072 .Sy gzip 1073 level by using the value 1074 .Sy gzip- Ns Em N , 1075 where 1076 .Em N 1077 is an integer from 1 1078 .Pq fastest 1079 to 9 1080 .Pq best compression ratio . 1081 Currently, 1082 .Sy gzip 1083 is equivalent to 1084 .Sy gzip-6 1085 .Po which is also the default for 1086 .Xr gzip 1 1087 .Pc . 1088 .Pp 1089 The 1090 .Sy zle 1091 compression algorithm compresses runs of zeros. 1092 .Pp 1093 This property can also be referred to by its shortened column name 1094 .Sy compress . 1095 Changing this property affects only newly-written data. 1096 .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 1097 Controls the number of copies of data stored for this dataset. 1098 These copies are in addition to any redundancy provided by the pool, for 1099 example, mirroring or RAID-Z. 1100 The copies are stored on different disks, if possible. 1101 The space used by multiple copies is charged to the associated file and dataset, 1102 changing the 1103 .Sy used 1104 property and counting against quotas and reservations. 1105 .Pp 1106 Changing this property only affects newly-written data. 1107 Therefore, set this property at file system creation time by using the 1108 .Fl o Sy copies Ns = Ns Ar N 1109 option. 1110 .It Sy devices Ns = Ns Sy on Ns | Ns Sy off 1111 Controls whether device nodes can be opened on this file system. 1112 The default value is 1113 .Sy on . 1114 .It Sy exec Ns = Ns Sy on Ns | Ns Sy off 1115 Controls whether processes can be executed from within this file system. 1116 The default value is 1117 .Sy on . 1118 .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none 1119 Limits the number of filesystems and volumes that can exist under this point in 1120 the dataset tree. 1121 The limit is not enforced if the user is allowed to change the limit. 1122 Setting a 1123 .Sy filesystem_limit 1124 to 1125 .Sy on 1126 a descendent of a filesystem that already has a 1127 .Sy filesystem_limit 1128 does not override the ancestor's 1129 .Sy filesystem_limit , 1130 but rather imposes an additional limit. 1131 This feature must be enabled to be used 1132 .Po see 1133 .Xr zpool-features 5 1134 .Pc . 1135 .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy 1136 Controls the mount point used for this file system. 1137 See the 1138 .Sx Mount Points 1139 section for more information on how this property is used. 1140 .Pp 1141 When the 1142 .Sy mountpoint 1143 property is changed for a file system, the file system and any children that 1144 inherit the mount point are unmounted. 1145 If the new value is 1146 .Sy legacy , 1147 then they remain unmounted. 1148 Otherwise, they are automatically remounted in the new location if the property 1149 was previously 1150 .Sy legacy 1151 or 1152 .Sy none , 1153 or if they were mounted before the property was changed. 1154 In addition, any shared file systems are unshared and shared in the new 1155 location. 1156 .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off 1157 Controls whether the file system should be mounted with 1158 .Sy nbmand 1159 .Pq Non Blocking mandatory locks . 1160 This is used for SMB clients. 1161 Changes to this property only take effect when the file system is umounted and 1162 remounted. 1163 See 1164 .Xr mount 1M 1165 for more information on 1166 .Sy nbmand 1167 mounts. 1168 .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata 1169 Controls what is cached in the primary cache 1170 .Pq ARC . 1171 If this property is set to 1172 .Sy all , 1173 then both user data and metadata is cached. 1174 If this property is set to 1175 .Sy none , 1176 then neither user data nor metadata is cached. 1177 If this property is set to 1178 .Sy metadata , 1179 then only metadata is cached. 1180 The default value is 1181 .Sy all . 1182 .It Sy quota Ns = Ns Em size Ns | Ns Sy none 1183 Limits the amount of space a dataset and its descendents can consume. 1184 This property enforces a hard limit on the amount of space used. 1185 This includes all space consumed by descendents, including file systems and 1186 snapshots. 1187 Setting a quota on a descendent of a dataset that already has a quota does not 1188 override the ancestor's quota, but rather imposes an additional limit. 1189 .Pp 1190 Quotas cannot be set on volumes, as the 1191 .Sy volsize 1192 property acts as an implicit quota. 1193 .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none 1194 Limits the number of snapshots that can be created on a dataset and its 1195 descendents. 1196 Setting a 1197 .Sy snapshot_limit 1198 on a descendent of a dataset that already has a 1199 .Sy snapshot_limit 1200 does not override the ancestor's 1201 .Sy snapshot_limit , 1202 but rather imposes an additional limit. 1203 The limit is not enforced if the user is allowed to change the limit. 1204 For example, this means that recursive snapshots taken from the global zone are 1205 counted against each delegated dataset within a zone. 1206 This feature must be enabled to be used 1207 .Po see 1208 .Xr zpool-features 5 1209 .Pc . 1210 .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none 1211 Limits the amount of space consumed by the specified user. 1212 User space consumption is identified by the 1213 .Sy userspace@ Ns Em user 1214 property. 1215 .Pp 1216 Enforcement of user quotas may be delayed by several seconds. 1217 This delay means that a user might exceed their quota before the system notices 1218 that they are over quota and begins to refuse additional writes with the 1219 .Er EDQUOT 1220 error message. 1221 See the 1222 .Nm zfs Cm userspace 1223 subcommand for more information. 1224 .Pp 1225 Unprivileged users can only access their own groups' space usage. 1226 The root user, or a user who has been granted the 1227 .Sy userquota 1228 privilege with 1229 .Nm zfs Cm allow , 1230 can get and set everyone's quota. 1231 .Pp 1232 This property is not available on volumes, on file systems before version 4, or 1233 on pools before version 15. 1234 The 1235 .Sy userquota@ Ns Em ... 1236 properties are not displayed by 1237 .Nm zfs Cm get Sy all . 1238 The user's name must be appended after the 1239 .Sy @ 1240 symbol, using one of the following forms: 1241 .Bl -bullet 1242 .It 1243 .Em POSIX name 1244 .Po for example, 1245 .Sy joe 1246 .Pc 1247 .It 1248 .Em POSIX numeric ID 1249 .Po for example, 1250 .Sy 789 1251 .Pc 1252 .It 1253 .Em SID name 1254 .Po for example, 1255 .Sy joe.smith@mydomain 1256 .Pc 1257 .It 1258 .Em SID numeric ID 1259 .Po for example, 1260 .Sy S-1-123-456-789 1261 .Pc 1262 .El 1263 .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none 1264 Limits the amount of space consumed by the specified group. 1265 Group space consumption is identified by the 1266 .Sy groupused@ Ns Em group 1267 property. 1268 .Pp 1269 Unprivileged users can access only their own groups' space usage. 1270 The root user, or a user who has been granted the 1271 .Sy groupquota 1272 privilege with 1273 .Nm zfs Cm allow , 1274 can get and set all groups' quotas. 1275 .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off 1276 Controls whether this dataset can be modified. 1277 The default value is 1278 .Sy off . 1279 .Pp 1280 This property can also be referred to by its shortened column name, 1281 .Sy rdonly . 1282 .It Sy recordsize Ns = Ns Em size 1283 Specifies a suggested block size for files in the file system. 1284 This property is designed solely for use with database workloads that access 1285 files in fixed-size records. 1286 ZFS automatically tunes block sizes according to internal algorithms optimized 1287 for typical access patterns. 1288 .Pp 1289 For databases that create very large files but access them in small random 1290 chunks, these algorithms may be suboptimal. 1291 Specifying a 1292 .Sy recordsize 1293 greater than or equal to the record size of the database can result in 1294 significant performance gains. 1295 Use of this property for general purpose file systems is strongly discouraged, 1296 and may adversely affect performance. 1297 .Pp 1298 The size specified must be a power of two greater than or equal to 512 and less 1299 than or equal to 128 Kbytes. 1300 If the 1301 .Sy large_blocks 1302 feature is enabled on the pool, the size may be up to 1 Mbyte. 1303 See 1304 .Xr zpool-features 5 1305 for details on ZFS feature flags. 1306 .Pp 1307 Changing the file system's 1308 .Sy recordsize 1309 affects only files created afterward; existing files are unaffected. 1310 .Pp 1311 This property can also be referred to by its shortened column name, 1312 .Sy recsize . 1313 .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most 1314 Controls what types of metadata are stored redundantly. 1315 ZFS stores an extra copy of metadata, so that if a single block is corrupted, 1316 the amount of user data lost is limited. 1317 This extra copy is in addition to any redundancy provided at the pool level 1318 .Pq e.g. by mirroring or RAID-Z , 1319 and is in addition to an extra copy specified by the 1320 .Sy copies 1321 property 1322 .Pq up to a total of 3 copies . 1323 For example if the pool is mirrored, 1324 .Sy copies Ns = Ns 2 , 1325 and 1326 .Sy redundant_metadata Ns = Ns Sy most , 1327 then ZFS stores 6 copies of most metadata, and 4 copies of data and some 1328 metadata. 1329 .Pp 1330 When set to 1331 .Sy all , 1332 ZFS stores an extra copy of all metadata. 1333 If a single on-disk block is corrupt, at worst a single block of user data 1334 .Po which is 1335 .Sy recordsize 1336 bytes long 1337 .Pc 1338 can be lost. 1339 .Pp 1340 When set to 1341 .Sy most , 1342 ZFS stores an extra copy of most types of metadata. 1343 This can improve performance of random writes, because less metadata must be 1344 written. 1345 In practice, at worst about 100 blocks 1346 .Po of 1347 .Sy recordsize 1348 bytes each 1349 .Pc 1350 of user data can be lost if a single on-disk block is corrupt. 1351 The exact behavior of which metadata blocks are stored redundantly may change in 1352 future releases. 1353 .Pp 1354 The default value is 1355 .Sy all . 1356 .It Sy refquota Ns = Ns Em size Ns | Ns Sy none 1357 Limits the amount of space a dataset can consume. 1358 This property enforces a hard limit on the amount of space used. 1359 This hard limit does not include space used by descendents, including file 1360 systems and snapshots. 1361 .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto 1362 The minimum amount of space guaranteed to a dataset, not including its 1363 descendents. 1364 When the amount of space used is below this value, the dataset is treated as if 1365 it were taking up the amount of space specified by 1366 .Sy refreservation . 1367 The 1368 .Sy refreservation 1369 reservation is accounted for in the parent datasets' space used, and counts 1370 against the parent datasets' quotas and reservations. 1371 .Pp 1372 If 1373 .Sy refreservation 1374 is set, a snapshot is only allowed if there is enough free pool space outside of 1375 this reservation to accommodate the current number of 1376 .Qq referenced 1377 bytes in the dataset. 1378 .Pp 1379 If 1380 .Sy refreservation 1381 is set to 1382 .Sy auto , 1383 a volume is thick provisioned 1384 .Po or 1385 .Qq not sparse 1386 .Pc . 1387 .Sy refreservation Ns = Ns Sy auto 1388 is only supported on volumes. 1389 See 1390 .Sy volsize 1391 in the 1392 .Sx Native Properties 1393 section for more information about sparse volumes. 1394 .Pp 1395 This property can also be referred to by its shortened column name, 1396 .Sy refreserv . 1397 .It Sy reservation Ns = Ns Em size Ns | Ns Sy none 1398 The minimum amount of space guaranteed to a dataset and its descendants. 1399 When the amount of space used is below this value, the dataset is treated as if 1400 it were taking up the amount of space specified by its reservation. 1401 Reservations are accounted for in the parent datasets' space used, and count 1402 against the parent datasets' quotas and reservations. 1403 .Pp 1404 This property can also be referred to by its shortened column name, 1405 .Sy reserv . 1406 .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata 1407 Controls what is cached in the secondary cache 1408 .Pq L2ARC . 1409 If this property is set to 1410 .Sy all , 1411 then both user data and metadata is cached. 1412 If this property is set to 1413 .Sy none , 1414 then neither user data nor metadata is cached. 1415 If this property is set to 1416 .Sy metadata , 1417 then only metadata is cached. 1418 The default value is 1419 .Sy all . 1420 .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off 1421 Controls whether the setuid bit is respected for the file system. 1422 The default value is 1423 .Sy on . 1424 .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts 1425 Controls whether the file system is shared via SMB, and what options are to be 1426 used. 1427 A file system with the 1428 .Sy sharesmb 1429 property set to 1430 .Sy off 1431 is managed through traditional tools such as 1432 .Xr sharemgr 1M . 1433 Otherwise, the file system is automatically shared and unshared with the 1434 .Nm zfs Cm share 1435 and 1436 .Nm zfs Cm unshare 1437 commands. 1438 If the property is set to 1439 .Sy on , 1440 the 1441 .Xr sharemgr 1M 1442 command is invoked with no options. 1443 Otherwise, the 1444 .Xr sharemgr 1M 1445 command is invoked with options equivalent to the contents of this property. 1446 .Pp 1447 Because SMB shares requires a resource name, a unique resource name is 1448 constructed from the dataset name. 1449 The constructed name is a copy of the dataset name except that the characters in 1450 the dataset name, which would be invalid in the resource name, are replaced with 1451 underscore 1452 .Pq Sy _ 1453 characters. 1454 A pseudo property 1455 .Qq name 1456 is also supported that allows you to replace the data set name with a specified 1457 name. 1458 The specified name is then used to replace the prefix dataset in the case of 1459 inheritance. 1460 For example, if the dataset 1461 .Em data/home/john 1462 is set to 1463 .Sy name Ns = Ns Sy john , 1464 then 1465 .Em data/home/john 1466 has a resource name of 1467 .Sy john . 1468 If a child dataset 1469 .Em data/home/john/backups 1470 is shared, it has a resource name of 1471 .Sy john_backups . 1472 .Pp 1473 When SMB shares are created, the SMB share name appears as an entry in the 1474 .Pa .zfs/shares 1475 directory. 1476 You can use the 1477 .Nm ls 1478 or 1479 .Nm chmod 1480 command to display the share-level ACLs on the entries in this directory. 1481 .Pp 1482 When the 1483 .Sy sharesmb 1484 property is changed for a dataset, the dataset and any children inheriting the 1485 property are re-shared with the new options, only if the property was previously 1486 set to 1487 .Sy off , 1488 or if they were shared before the property was changed. 1489 If the new property is set to 1490 .Sy off , 1491 the file systems are unshared. 1492 .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts 1493 Controls whether the file system is shared via NFS, and what options are to be 1494 used. 1495 A file system with a 1496 .Sy sharenfs 1497 property of 1498 .Sy off 1499 is managed through traditional tools such as 1500 .Xr share 1M , 1501 .Xr unshare 1M , 1502 and 1503 .Xr dfstab 4 . 1504 Otherwise, the file system is automatically shared and unshared with the 1505 .Nm zfs Cm share 1506 and 1507 .Nm zfs Cm unshare 1508 commands. 1509 If the property is set to 1510 .Sy on , 1511 .Xr share 1M 1512 command is invoked with no options. 1513 Otherwise, the 1514 .Xr share 1M 1515 command is invoked with options equivalent to the contents of this property. 1516 .Pp 1517 When the 1518 .Sy sharenfs 1519 property is changed for a dataset, the dataset and any children inheriting the 1520 property are re-shared with the new options, only if the property was previously 1521 .Sy off , 1522 or if they were shared before the property was changed. 1523 If the new property is 1524 .Sy off , 1525 the file systems are unshared. 1526 .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput 1527 Provide a hint to ZFS about handling of synchronous requests in this dataset. 1528 If 1529 .Sy logbias 1530 is set to 1531 .Sy latency 1532 .Pq the default , 1533 ZFS will use pool log devices 1534 .Pq if configured 1535 to handle the requests at low latency. 1536 If 1537 .Sy logbias 1538 is set to 1539 .Sy throughput , 1540 ZFS will not use configured pool log devices. 1541 ZFS will instead optimize synchronous operations for global pool throughput and 1542 efficient use of resources. 1543 .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible 1544 Controls whether the 1545 .Pa .zfs 1546 directory is hidden or visible in the root of the file system as discussed in 1547 the 1548 .Sx Snapshots 1549 section. 1550 The default value is 1551 .Sy hidden . 1552 .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled 1553 Controls the behavior of synchronous requests 1554 .Pq e.g. fsync, O_DSYNC . 1555 .Sy standard 1556 is the 1557 .Tn POSIX 1558 specified behavior of ensuring all synchronous requests are written to stable 1559 storage and all devices are flushed to ensure data is not cached by device 1560 controllers 1561 .Pq this is the default . 1562 .Sy always 1563 causes every file system transaction to be written and flushed before its 1564 system call returns. 1565 This has a large performance penalty. 1566 .Sy disabled 1567 disables synchronous requests. 1568 File system transactions are only committed to stable storage periodically. 1569 This option will give the highest performance. 1570 However, it is very dangerous as ZFS would be ignoring the synchronous 1571 transaction demands of applications such as databases or NFS. 1572 Administrators should only use this option when the risks are understood. 1573 .It Sy version Ns = Ns Em N Ns | Ns Sy current 1574 The on-disk version of this file system, which is independent of the pool 1575 version. 1576 This property can only be set to later supported versions. 1577 See the 1578 .Nm zfs Cm upgrade 1579 command. 1580 .It Sy volsize Ns = Ns Em size 1581 For volumes, specifies the logical size of the volume. 1582 By default, creating a volume establishes a reservation of equal size. 1583 For storage pools with a version number of 9 or higher, a 1584 .Sy refreservation 1585 is set instead. 1586 Any changes to 1587 .Sy volsize 1588 are reflected in an equivalent change to the reservation 1589 .Po or 1590 .Sy refreservation 1591 .Pc . 1592 The 1593 .Sy volsize 1594 can only be set to a multiple of 1595 .Sy volblocksize , 1596 and cannot be zero. 1597 .Pp 1598 The reservation is kept equal to the volume's logical size to prevent unexpected 1599 behavior for consumers. 1600 Without the reservation, the volume could run out of space, resulting in 1601 undefined behavior or data corruption, depending on how the volume is used. 1602 These effects can also occur when the volume size is changed while it is in use 1603 .Pq particularly when shrinking the size . 1604 Extreme care should be used when adjusting the volume size. 1605 .Pp 1606 Though not recommended, a 1607 .Qq sparse volume 1608 .Po also known as 1609 .Qq thin provisioned 1610 .Pc 1611 can be created by specifying the 1612 .Fl s 1613 option to the 1614 .Nm zfs Cm create Fl V 1615 command, or by changing the value of the 1616 .Sy refreservation 1617 property 1618 .Po or 1619 .Sy reservation 1620 property on pool version 8 or earlier 1621 .Pc 1622 after the volume has been created. 1623 A 1624 .Qq sparse volume 1625 is a volume where the value of 1626 .Sy refreservation 1627 is less than the size of the volume plus the space required to store its 1628 metadata. 1629 Consequently, writes to a sparse volume can fail with 1630 .Er ENOSPC 1631 when the pool is low on space. 1632 For a sparse volume, changes to 1633 .Sy volsize 1634 are not reflected in the 1635 .Sy refreservation. 1636 A volume that is not sparse is said to be 1637 .Qq thick provisioned . 1638 A sparse volume can become thick provisioned by setting 1639 .Sy refreservation 1640 to 1641 .Sy auto . 1642 .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off 1643 Controls whether regular files should be scanned for viruses when a file is 1644 opened and closed. 1645 In addition to enabling this property, the virus scan service must also be 1646 enabled for virus scanning to occur. 1647 The default value is 1648 .Sy off . 1649 .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off 1650 Controls whether extended attributes are enabled for this file system. 1651 The default value is 1652 .Sy on . 1653 .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off 1654 Controls whether the dataset is managed from a non-global zone. 1655 See the 1656 .Sx Zones 1657 section for more information. 1658 The default value is 1659 .Sy off . 1660 .El 1661 .Pp 1662 The following three properties cannot be changed after the file system is 1663 created, and therefore, should be set when the file system is created. 1664 If the properties are not set with the 1665 .Nm zfs Cm create 1666 or 1667 .Nm zpool Cm create 1668 commands, these properties are inherited from the parent dataset. 1669 If the parent dataset lacks these properties due to having been created prior to 1670 these features being supported, the new file system will have the default values 1671 for these properties. 1672 .Bl -tag -width "" 1673 .It Xo 1674 .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns 1675 .Sy insensitive Ns | Ns Sy mixed 1676 .Xc 1677 Indicates whether the file name matching algorithm used by the file system 1678 should be case-sensitive, case-insensitive, or allow a combination of both 1679 styles of matching. 1680 The default value for the 1681 .Sy casesensitivity 1682 property is 1683 .Sy sensitive . 1684 Traditionally, 1685 .Ux 1686 and 1687 .Tn POSIX 1688 file systems have case-sensitive file names. 1689 .Pp 1690 The 1691 .Sy mixed 1692 value for the 1693 .Sy casesensitivity 1694 property indicates that the file system can support requests for both 1695 case-sensitive and case-insensitive matching behavior. 1696 Currently, case-insensitive matching behavior on a file system that supports 1697 mixed behavior is limited to the SMB server product. 1698 For more information about the 1699 .Sy mixed 1700 value behavior, see the "ZFS Administration Guide". 1701 .It Xo 1702 .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns 1703 .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD 1704 .Xc 1705 Indicates whether the file system should perform a 1706 .Sy unicode 1707 normalization of file names whenever two file names are compared, and which 1708 normalization algorithm should be used. 1709 File names are always stored unmodified, names are normalized as part of any 1710 comparison process. 1711 If this property is set to a legal value other than 1712 .Sy none , 1713 and the 1714 .Sy utf8only 1715 property was left unspecified, the 1716 .Sy utf8only 1717 property is automatically set to 1718 .Sy on . 1719 The default value of the 1720 .Sy normalization 1721 property is 1722 .Sy none . 1723 This property cannot be changed after the file system is created. 1724 .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off 1725 Indicates whether the file system should reject file names that include 1726 characters that are not present in the 1727 .Sy UTF-8 1728 character code set. 1729 If this property is explicitly set to 1730 .Sy off , 1731 the normalization property must either not be explicitly set or be set to 1732 .Sy none . 1733 The default value for the 1734 .Sy utf8only 1735 property is 1736 .Sy off . 1737 This property cannot be changed after the file system is created. 1738 .El 1739 .Pp 1740 The 1741 .Sy casesensitivity , 1742 .Sy normalization , 1743 and 1744 .Sy utf8only 1745 properties are also new permissions that can be assigned to non-privileged users 1746 by using the ZFS delegated administration feature. 1747 .Ss "Temporary Mount Point Properties" 1748 When a file system is mounted, either through 1749 .Xr mount 1M 1750 for legacy mounts or the 1751 .Nm zfs Cm mount 1752 command for normal file systems, its mount options are set according to its 1753 properties. 1754 The correlation between properties and mount options is as follows: 1755 .Bd -literal 1756 PROPERTY MOUNT OPTION 1757 devices devices/nodevices 1758 exec exec/noexec 1759 readonly ro/rw 1760 setuid setuid/nosetuid 1761 xattr xattr/noxattr 1762 .Ed 1763 .Pp 1764 In addition, these options can be set on a per-mount basis using the 1765 .Fl o 1766 option, without affecting the property that is stored on disk. 1767 The values specified on the command line override the values stored in the 1768 dataset. 1769 The 1770 .Sy nosuid 1771 option is an alias for 1772 .Sy nodevices Ns \&, Ns Sy nosetuid . 1773 These properties are reported as 1774 .Qq temporary 1775 by the 1776 .Nm zfs Cm get 1777 command. 1778 If the properties are changed while the dataset is mounted, the new setting 1779 overrides any temporary settings. 1780 .Ss "User Properties" 1781 In addition to the standard native properties, ZFS supports arbitrary user 1782 properties. 1783 User properties have no effect on ZFS behavior, but applications or 1784 administrators can use them to annotate datasets 1785 .Pq file systems, volumes, and snapshots . 1786 .Pp 1787 User property names must contain a colon 1788 .Pq Qq Sy \&: 1789 character to distinguish them from native properties. 1790 They may contain lowercase letters, numbers, and the following punctuation 1791 characters: colon 1792 .Pq Qq Sy \&: , 1793 dash 1794 .Pq Qq Sy - , 1795 period 1796 .Pq Qq Sy \&. , 1797 and underscore 1798 .Pq Qq Sy _ . 1799 The expected convention is that the property name is divided into two portions 1800 such as 1801 .Em module Ns \&: Ns Em property , 1802 but this namespace is not enforced by ZFS. 1803 User property names can be at most 256 characters, and cannot begin with a dash 1804 .Pq Qq Sy - . 1805 .Pp 1806 When making programmatic use of user properties, it is strongly suggested to use 1807 a reversed 1808 .Sy DNS 1809 domain name for the 1810 .Em module 1811 component of property names to reduce the chance that two 1812 independently-developed packages use the same property name for different 1813 purposes. 1814 .Pp 1815 The values of user properties are arbitrary strings, are always inherited, and 1816 are never validated. 1817 All of the commands that operate on properties 1818 .Po Nm zfs Cm list , 1819 .Nm zfs Cm get , 1820 .Nm zfs Cm set , 1821 and so forth 1822 .Pc 1823 can be used to manipulate both native properties and user properties. 1824 Use the 1825 .Nm zfs Cm inherit 1826 command to clear a user property. 1827 If the property is not defined in any parent dataset, it is removed entirely. 1828 Property values are limited to 8192 bytes. 1829 .Ss ZFS Volumes as Swap or Dump Devices 1830 During an initial installation a swap device and dump device are created on ZFS 1831 volumes in the ZFS root pool. 1832 By default, the swap area size is based on 1/2 the size of physical memory up to 1833 2 Gbytes. 1834 The size of the dump device depends on the kernel's requirements at installation 1835 time. 1836 Separate ZFS volumes must be used for the swap area and dump devices. 1837 Do not swap to a file on a ZFS file system. 1838 A ZFS swap file configuration is not supported. 1839 .Pp 1840 If you need to change your swap area or dump device after the system is 1841 installed or upgraded, use the 1842 .Xr swap 1M 1843 and 1844 .Xr dumpadm 1M 1845 commands. 1846 .Sh SUBCOMMANDS 1847 All subcommands that modify state are logged persistently to the pool in their 1848 original form. 1849 .Bl -tag -width "" 1850 .It Nm Fl \? 1851 Displays a help message. 1852 .It Xo 1853 .Nm 1854 .Cm create 1855 .Op Fl p 1856 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 1857 .Ar filesystem 1858 .Xc 1859 Creates a new ZFS file system. 1860 The file system is automatically mounted according to the 1861 .Sy mountpoint 1862 property inherited from the parent. 1863 .Bl -tag -width "-o" 1864 .It Fl o Ar property Ns = Ns Ar value 1865 Sets the specified property as if the command 1866 .Nm zfs Cm set Ar property Ns = Ns Ar value 1867 was invoked at the same time the dataset was created. 1868 Any editable ZFS property can also be set at creation time. 1869 Multiple 1870 .Fl o 1871 options can be specified. 1872 An error results if the same property is specified in multiple 1873 .Fl o 1874 options. 1875 .It Fl p 1876 Creates all the non-existing parent datasets. 1877 Datasets created in this manner are automatically mounted according to the 1878 .Sy mountpoint 1879 property inherited from their parent. 1880 Any property specified on the command line using the 1881 .Fl o 1882 option is ignored. 1883 If the target filesystem already exists, the operation completes successfully. 1884 .El 1885 .It Xo 1886 .Nm 1887 .Cm create 1888 .Op Fl ps 1889 .Op Fl b Ar blocksize 1890 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 1891 .Fl V Ar size Ar volume 1892 .Xc 1893 Creates a volume of the given size. 1894 The volume is exported as a block device in 1895 .Pa /dev/zvol/{dsk,rdsk}/path , 1896 where 1897 .Em path 1898 is the name of the volume in the ZFS namespace. 1899 The size represents the logical size as exported by the device. 1900 By default, a reservation of equal size is created. 1901 .Pp 1902 .Ar size 1903 is automatically rounded up to the nearest 128 Kbytes to ensure that the volume 1904 has an integral number of blocks regardless of 1905 .Sy blocksize . 1906 .Bl -tag -width "-b" 1907 .It Fl b Ar blocksize 1908 Equivalent to 1909 .Fl o Sy volblocksize Ns = Ns Ar blocksize . 1910 If this option is specified in conjunction with 1911 .Fl o Sy volblocksize , 1912 the resulting behavior is undefined. 1913 .It Fl o Ar property Ns = Ns Ar value 1914 Sets the specified property as if the 1915 .Nm zfs Cm set Ar property Ns = Ns Ar value 1916 command was invoked at the same time the dataset was created. 1917 Any editable ZFS property can also be set at creation time. 1918 Multiple 1919 .Fl o 1920 options can be specified. 1921 An error results if the same property is specified in multiple 1922 .Fl o 1923 options. 1924 .It Fl p 1925 Creates all the non-existing parent datasets. 1926 Datasets created in this manner are automatically mounted according to the 1927 .Sy mountpoint 1928 property inherited from their parent. 1929 Any property specified on the command line using the 1930 .Fl o 1931 option is ignored. 1932 If the target filesystem already exists, the operation completes successfully. 1933 .It Fl s 1934 Creates a sparse volume with no reservation. 1935 See 1936 .Sy volsize 1937 in the 1938 .Sx Native Properties 1939 section for more information about sparse volumes. 1940 .El 1941 .It Xo 1942 .Nm 1943 .Cm destroy 1944 .Op Fl Rfnprv 1945 .Ar filesystem Ns | Ns Ar volume 1946 .Xc 1947 Destroys the given dataset. 1948 By default, the command unshares any file systems that are currently shared, 1949 unmounts any file systems that are currently mounted, and refuses to destroy a 1950 dataset that has active dependents 1951 .Pq children or clones . 1952 .Bl -tag -width "-R" 1953 .It Fl R 1954 Recursively destroy all dependents, including cloned file systems outside the 1955 target hierarchy. 1956 .It Fl f 1957 Force an unmount of any file systems using the 1958 .Nm unmount Fl f 1959 command. 1960 This option has no effect on non-file systems or unmounted file systems. 1961 .It Fl n 1962 Do a dry-run 1963 .Pq Qq No-op 1964 deletion. 1965 No data will be deleted. 1966 This is useful in conjunction with the 1967 .Fl v 1968 or 1969 .Fl p 1970 flags to determine what data would be deleted. 1971 .It Fl p 1972 Print machine-parsable verbose information about the deleted data. 1973 .It Fl r 1974 Recursively destroy all children. 1975 .It Fl v 1976 Print verbose information about the deleted data. 1977 .El 1978 .Pp 1979 Extreme care should be taken when applying either the 1980 .Fl r 1981 or the 1982 .Fl R 1983 options, as they can destroy large portions of a pool and cause unexpected 1984 behavior for mounted file systems in use. 1985 .It Xo 1986 .Nm 1987 .Cm destroy 1988 .Op Fl Rdnprv 1989 .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns 1990 .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... 1991 .Xc 1992 The given snapshots are destroyed immediately if and only if the 1993 .Nm zfs Cm destroy 1994 command without the 1995 .Fl d 1996 option would have destroyed it. 1997 Such immediate destruction would occur, for example, if the snapshot had no 1998 clones and the user-initiated reference count were zero. 1999 .Pp 2000 If a snapshot does not qualify for immediate destruction, it is marked for 2001 deferred deletion. 2002 In this state, it exists as a usable, visible snapshot until both of the 2003 preconditions listed above are met, at which point it is destroyed. 2004 .Pp 2005 An inclusive range of snapshots may be specified by separating the first and 2006 last snapshots with a percent sign. 2007 The first and/or last snapshots may be left blank, in which case the 2008 filesystem's oldest or newest snapshot will be implied. 2009 .Pp 2010 Multiple snapshots 2011 .Pq or ranges of snapshots 2012 of the same filesystem or volume may be specified in a comma-separated list of 2013 snapshots. 2014 Only the snapshot's short name 2015 .Po the part after the 2016 .Sy @ 2017 .Pc 2018 should be specified when using a range or comma-separated list to identify 2019 multiple snapshots. 2020 .Bl -tag -width "-R" 2021 .It Fl R 2022 Recursively destroy all clones of these snapshots, including the clones, 2023 snapshots, and children. 2024 If this flag is specified, the 2025 .Fl d 2026 flag will have no effect. 2027 .It Fl d 2028 Defer snapshot deletion. 2029 .It Fl n 2030 Do a dry-run 2031 .Pq Qq No-op 2032 deletion. 2033 No data will be deleted. 2034 This is useful in conjunction with the 2035 .Fl p 2036 or 2037 .Fl v 2038 flags to determine what data would be deleted. 2039 .It Fl p 2040 Print machine-parsable verbose information about the deleted data. 2041 .It Fl r 2042 Destroy 2043 .Pq or mark for deferred deletion 2044 all snapshots with this name in descendent file systems. 2045 .It Fl v 2046 Print verbose information about the deleted data. 2047 .Pp 2048 Extreme care should be taken when applying either the 2049 .Fl r 2050 or the 2051 .Fl R 2052 options, as they can destroy large portions of a pool and cause unexpected 2053 behavior for mounted file systems in use. 2054 .El 2055 .It Xo 2056 .Nm 2057 .Cm destroy 2058 .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark 2059 .Xc 2060 The given bookmark is destroyed. 2061 .It Xo 2062 .Nm 2063 .Cm snapshot 2064 .Op Fl r 2065 .Oo Fl o Ar property Ns = Ns value Oc Ns ... 2066 .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... 2067 .Xc 2068 Creates snapshots with the given names. 2069 All previous modifications by successful system calls to the file system are 2070 part of the snapshots. 2071 Snapshots are taken atomically, so that all snapshots correspond to the same 2072 moment in time. 2073 See the 2074 .Sx Snapshots 2075 section for details. 2076 .Bl -tag -width "-o" 2077 .It Fl o Ar property Ns = Ns Ar value 2078 Sets the specified property; see 2079 .Nm zfs Cm create 2080 for details. 2081 .It Fl r 2082 Recursively create snapshots of all descendent datasets 2083 .El 2084 .It Xo 2085 .Nm 2086 .Cm rollback 2087 .Op Fl Rfr 2088 .Ar snapshot 2089 .Xc 2090 Roll back the given dataset to a previous snapshot. 2091 When a dataset is rolled back, all data that has changed since the snapshot is 2092 discarded, and the dataset reverts to the state at the time of the snapshot. 2093 By default, the command refuses to roll back to a snapshot other than the most 2094 recent one. 2095 In order to do so, all intermediate snapshots and bookmarks must be destroyed by 2096 specifying the 2097 .Fl r 2098 option. 2099 .Pp 2100 The 2101 .Fl rR 2102 options do not recursively destroy the child snapshots of a recursive snapshot. 2103 Only direct snapshots of the specified filesystem are destroyed by either of 2104 these options. 2105 To completely roll back a recursive snapshot, you must rollback the individual 2106 child snapshots. 2107 .Bl -tag -width "-R" 2108 .It Fl R 2109 Destroy any more recent snapshots and bookmarks, as well as any clones of those 2110 snapshots. 2111 .It Fl f 2112 Used with the 2113 .Fl R 2114 option to force an unmount of any clone file systems that are to be destroyed. 2115 .It Fl r 2116 Destroy any snapshots and bookmarks more recent than the one specified. 2117 .El 2118 .It Xo 2119 .Nm 2120 .Cm clone 2121 .Op Fl p 2122 .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... 2123 .Ar snapshot Ar filesystem Ns | Ns Ar volume 2124 .Xc 2125 Creates a clone of the given snapshot. 2126 See the 2127 .Sx Clones 2128 section for details. 2129 The target dataset can be located anywhere in the ZFS hierarchy, and is created 2130 as the same type as the original. 2131 .Bl -tag -width "-o" 2132 .It Fl o Ar property Ns = Ns Ar value 2133 Sets the specified property; see 2134 .Nm zfs Cm create 2135 for details. 2136 .It Fl p 2137 Creates all the non-existing parent datasets. 2138 Datasets created in this manner are automatically mounted according to the 2139 .Sy mountpoint 2140 property inherited from their parent. 2141 If the target filesystem or volume already exists, the operation completes 2142 successfully. 2143 .El 2144 .It Xo 2145 .Nm 2146 .Cm promote 2147 .Ar clone-filesystem 2148 .Xc 2149 Promotes a clone file system to no longer be dependent on its 2150 .Qq origin 2151 snapshot. 2152 This makes it possible to destroy the file system that the clone was created 2153 from. 2154 The clone parent-child dependency relationship is reversed, so that the origin 2155 file system becomes a clone of the specified file system. 2156 .Pp 2157 The snapshot that was cloned, and any snapshots previous to this snapshot, are 2158 now owned by the promoted clone. 2159 The space they use moves from the origin file system to the promoted clone, so 2160 enough space must be available to accommodate these snapshots. 2161 No new space is consumed by this operation, but the space accounting is 2162 adjusted. 2163 The promoted clone must not have any conflicting snapshot names of its own. 2164 The 2165 .Cm rename 2166 subcommand can be used to rename any conflicting snapshots. 2167 .It Xo 2168 .Nm 2169 .Cm rename 2170 .Op Fl f 2171 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 2172 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 2173 .Xc 2174 .It Xo 2175 .Nm 2176 .Cm rename 2177 .Op Fl fp 2178 .Ar filesystem Ns | Ns Ar volume 2179 .Ar filesystem Ns | Ns Ar volume 2180 .Xc 2181 Renames the given dataset. 2182 The new target can be located anywhere in the ZFS hierarchy, with the exception 2183 of snapshots. 2184 Snapshots can only be renamed within the parent file system or volume. 2185 When renaming a snapshot, the parent file system of the snapshot does not need 2186 to be specified as part of the second argument. 2187 Renamed file systems can inherit new mount points, in which case they are 2188 unmounted and remounted at the new mount point. 2189 .Bl -tag -width "-a" 2190 .It Fl f 2191 Force unmount any filesystems that need to be unmounted in the process. 2192 .It Fl p 2193 Creates all the nonexistent parent datasets. 2194 Datasets created in this manner are automatically mounted according to the 2195 .Sy mountpoint 2196 property inherited from their parent. 2197 .El 2198 .It Xo 2199 .Nm 2200 .Cm rename 2201 .Fl r 2202 .Ar snapshot Ar snapshot 2203 .Xc 2204 Recursively rename the snapshots of all descendent datasets. 2205 Snapshots are the only dataset that can be renamed recursively. 2206 .It Xo 2207 .Nm 2208 .Cm list 2209 .Op Fl r Ns | Ns Fl d Ar depth 2210 .Op Fl Hp 2211 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc 2212 .Oo Fl s Ar property Oc Ns ... 2213 .Oo Fl S Ar property Oc Ns ... 2214 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 2215 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... 2216 .Xc 2217 Lists the property information for the given datasets in tabular form. 2218 If specified, you can list property information by the absolute pathname or the 2219 relative pathname. 2220 By default, all file systems and volumes are displayed. 2221 Snapshots are displayed if the 2222 .Sy listsnaps 2223 property is 2224 .Sy on 2225 .Po the default is 2226 .Sy off 2227 .Pc . 2228 The following fields are displayed, 2229 .Sy name Ns \&, Ns Sy used Ns \&, Ns Sy available Ns \&, Ns Sy referenced Ns \&, Ns 2230 .Sy mountpoint . 2231 .Bl -tag -width "-H" 2232 .It Fl H 2233 Used for scripting mode. 2234 Do not print headers and separate fields by a single tab instead of arbitrary 2235 white space. 2236 .It Fl S Ar property 2237 Same as the 2238 .Fl s 2239 option, but sorts by property in descending order. 2240 .It Fl d Ar depth 2241 Recursively display any children of the dataset, limiting the recursion to 2242 .Ar depth . 2243 A 2244 .Ar depth 2245 of 2246 .Sy 1 2247 will display only the dataset and its direct children. 2248 .It Fl o Ar property 2249 A comma-separated list of properties to display. 2250 The property must be: 2251 .Bl -bullet 2252 .It 2253 One of the properties described in the 2254 .Sx Native Properties 2255 section 2256 .It 2257 A user property 2258 .It 2259 The value 2260 .Sy name 2261 to display the dataset name 2262 .It 2263 The value 2264 .Sy space 2265 to display space usage properties on file systems and volumes. 2266 This is a shortcut for specifying 2267 .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns 2268 .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t 2269 .Sy filesystem Ns \&, Ns Sy volume 2270 syntax. 2271 .El 2272 .It Fl p 2273 Display numbers in parsable 2274 .Pq exact 2275 values. 2276 .It Fl r 2277 Recursively display any children of the dataset on the command line. 2278 .It Fl s Ar property 2279 A property for sorting the output by column in ascending order based on the 2280 value of the property. 2281 The property must be one of the properties described in the 2282 .Sx Properties 2283 section, or the special value 2284 .Sy name 2285 to sort by the dataset name. 2286 Multiple properties can be specified at one time using multiple 2287 .Fl s 2288 property options. 2289 Multiple 2290 .Fl s 2291 options are evaluated from left to right in decreasing order of importance. 2292 The following is a list of sorting criteria: 2293 .Bl -bullet 2294 .It 2295 Numeric types sort in numeric order. 2296 .It 2297 String types sort in alphabetical order. 2298 .It 2299 Types inappropriate for a row sort that row to the literal bottom, regardless of 2300 the specified ordering. 2301 .El 2302 .Pp 2303 If no sorting options are specified the existing behavior of 2304 .Nm zfs Cm list 2305 is preserved. 2306 .It Fl t Ar type 2307 A comma-separated list of types to display, where 2308 .Ar type 2309 is one of 2310 .Sy filesystem , 2311 .Sy snapshot , 2312 .Sy volume , 2313 .Sy bookmark , 2314 or 2315 .Sy all . 2316 For example, specifying 2317 .Fl t Sy snapshot 2318 displays only snapshots. 2319 .El 2320 .It Xo 2321 .Nm 2322 .Cm set 2323 .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... 2324 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... 2325 .Xc 2326 Sets the property or list of properties to the given value(s) for each dataset. 2327 Only some properties can be edited. 2328 See the 2329 .Sx Properties 2330 section for more information on what properties can be set and acceptable 2331 values. 2332 Numeric values can be specified as exact values, or in a human-readable form 2333 with a suffix of 2334 .Sy B , K , M , G , T , P , E , Z 2335 .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, 2336 or zettabytes, respectively 2337 .Pc . 2338 User properties can be set on snapshots. 2339 For more information, see the 2340 .Sx User Properties 2341 section. 2342 .It Xo 2343 .Nm 2344 .Cm get 2345 .Op Fl r Ns | Ns Fl d Ar depth 2346 .Op Fl Hp 2347 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 2348 .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc 2349 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 2350 .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... 2351 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Ns ... 2352 .Xc 2353 Displays properties for the given datasets. 2354 If no datasets are specified, then the command displays properties for all 2355 datasets on the system. 2356 For each property, the following columns are displayed: 2357 .Bd -literal 2358 name Dataset name 2359 property Property name 2360 value Property value 2361 source Property source. Can either be local, default, 2362 temporary, inherited, or none (-). 2363 .Ed 2364 .Pp 2365 All columns are displayed by default, though this can be controlled by using the 2366 .Fl o 2367 option. 2368 This command takes a comma-separated list of properties as described in the 2369 .Sx Native Properties 2370 and 2371 .Sx User Properties 2372 sections. 2373 .Pp 2374 The special value 2375 .Sy all 2376 can be used to display all properties that apply to the given dataset's type 2377 .Pq filesystem, volume, snapshot, or bookmark . 2378 .Bl -tag -width "-H" 2379 .It Fl H 2380 Display output in a form more easily parsed by scripts. 2381 Any headers are omitted, and fields are explicitly separated by a single tab 2382 instead of an arbitrary amount of space. 2383 .It Fl d Ar depth 2384 Recursively display any children of the dataset, limiting the recursion to 2385 .Ar depth . 2386 A depth of 2387 .Sy 1 2388 will display only the dataset and its direct children. 2389 .It Fl o Ar field 2390 A comma-separated list of columns to display. 2391 .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source 2392 is the default value. 2393 .It Fl p 2394 Display numbers in parsable 2395 .Pq exact 2396 values. 2397 .It Fl r 2398 Recursively display properties for any children. 2399 .It Fl s Ar source 2400 A comma-separated list of sources to display. 2401 Those properties coming from a source other than those in this list are ignored. 2402 Each source must be one of the following: 2403 .Sy local , 2404 .Sy default , 2405 .Sy inherited , 2406 .Sy temporary , 2407 and 2408 .Sy none . 2409 The default value is all sources. 2410 .It Fl t Ar type 2411 A comma-separated list of types to display, where 2412 .Ar type 2413 is one of 2414 .Sy filesystem , 2415 .Sy snapshot , 2416 .Sy volume , 2417 .Sy bookmark , 2418 or 2419 .Sy all . 2420 .El 2421 .It Xo 2422 .Nm 2423 .Cm inherit 2424 .Op Fl rS 2425 .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... 2426 .Xc 2427 Clears the specified property, causing it to be inherited from an ancestor, 2428 restored to default if no ancestor has the property set, or with the 2429 .Fl S 2430 option reverted to the received value if one exists. 2431 See the 2432 .Sx Properties 2433 section for a listing of default values, and details on which properties can be 2434 inherited. 2435 .Bl -tag -width "-r" 2436 .It Fl r 2437 Recursively inherit the given property for all children. 2438 .It Fl S 2439 Revert the property to the received value if one exists; otherwise operate as 2440 if the 2441 .Fl S 2442 option was not specified. 2443 .El 2444 .It Xo 2445 .Nm 2446 .Cm remap 2447 .Ar filesystem Ns | Ns Ar volume 2448 .Xc 2449 Remap the indirect blocks in the given fileystem or volume so that they no 2450 longer reference blocks on previously removed vdevs and we can eventually 2451 shrink the size of the indirect mapping objects for the previously removed 2452 vdevs. Note that remapping all blocks might not be possible and that 2453 references from snapshots will still exist and cannot be remapped. 2454 .It Xo 2455 .Nm 2456 .Cm upgrade 2457 .Xc 2458 Displays a list of file systems that are not the most recent version. 2459 .It Xo 2460 .Nm 2461 .Cm upgrade 2462 .Fl v 2463 .Xc 2464 Displays a list of currently supported file system versions. 2465 .It Xo 2466 .Nm 2467 .Cm upgrade 2468 .Op Fl r 2469 .Op Fl V Ar version 2470 .Fl a | Ar filesystem 2471 .Xc 2472 Upgrades file systems to a new on-disk version. 2473 Once this is done, the file systems will no longer be accessible on systems 2474 running older versions of the software. 2475 .Nm zfs Cm send 2476 streams generated from new snapshots of these file systems cannot be accessed on 2477 systems running older versions of the software. 2478 .Pp 2479 In general, the file system version is independent of the pool version. 2480 See 2481 .Xr zpool 1M 2482 for information on the 2483 .Nm zpool Cm upgrade 2484 command. 2485 .Pp 2486 In some cases, the file system version and the pool version are interrelated and 2487 the pool version must be upgraded before the file system version can be 2488 upgraded. 2489 .Bl -tag -width "-V" 2490 .It Fl V Ar version 2491 Upgrade to the specified 2492 .Ar version . 2493 If the 2494 .Fl V 2495 flag is not specified, this command upgrades to the most recent version. 2496 This 2497 option can only be used to increase the version number, and only up to the most 2498 recent version supported by this software. 2499 .It Fl a 2500 Upgrade all file systems on all imported pools. 2501 .It Ar filesystem 2502 Upgrade the specified file system. 2503 .It Fl r 2504 Upgrade the specified file system and all descendent file systems. 2505 .El 2506 .It Xo 2507 .Nm 2508 .Cm userspace 2509 .Op Fl Hinp 2510 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 2511 .Oo Fl s Ar field Oc Ns ... 2512 .Oo Fl S Ar field Oc Ns ... 2513 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 2514 .Ar filesystem Ns | Ns Ar snapshot 2515 .Xc 2516 Displays space consumed by, and quotas on, each user in the specified filesystem 2517 or snapshot. 2518 This corresponds to the 2519 .Sy userused@ Ns Em user 2520 and 2521 .Sy userquota@ Ns Em user 2522 properties. 2523 .Bl -tag -width "-H" 2524 .It Fl H 2525 Do not print headers, use tab-delimited output. 2526 .It Fl S Ar field 2527 Sort by this field in reverse order. 2528 See 2529 .Fl s . 2530 .It Fl i 2531 Translate SID to POSIX ID. 2532 The POSIX ID may be ephemeral if no mapping exists. 2533 Normal POSIX interfaces 2534 .Po for example, 2535 .Xr stat 2 , 2536 .Nm ls Fl l 2537 .Pc 2538 perform this translation, so the 2539 .Fl i 2540 option allows the output from 2541 .Nm zfs Cm userspace 2542 to be compared directly with those utilities. 2543 However, 2544 .Fl i 2545 may lead to confusion if some files were created by an SMB user before a 2546 SMB-to-POSIX name mapping was established. 2547 In such a case, some files will be owned by the SMB entity and some by the POSIX 2548 entity. 2549 However, the 2550 .Fl i 2551 option will report that the POSIX entity has the total usage and quota for both. 2552 .It Fl n 2553 Print numeric ID instead of user/group name. 2554 .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... 2555 Display only the specified fields from the following set: 2556 .Sy type , 2557 .Sy name , 2558 .Sy used , 2559 .Sy quota . 2560 The default is to display all fields. 2561 .It Fl p 2562 Use exact 2563 .Pq parsable 2564 numeric output. 2565 .It Fl s Ar field 2566 Sort output by this field. 2567 The 2568 .Fl s 2569 and 2570 .Fl S 2571 flags may be specified multiple times to sort first by one field, then by 2572 another. 2573 The default is 2574 .Fl s Sy type Fl s Sy name . 2575 .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... 2576 Print only the specified types from the following set: 2577 .Sy all , 2578 .Sy posixuser , 2579 .Sy smbuser , 2580 .Sy posixgroup , 2581 .Sy smbgroup . 2582 The default is 2583 .Fl t Sy posixuser Ns \&, Ns Sy smbuser . 2584 The default can be changed to include group types. 2585 .El 2586 .It Xo 2587 .Nm 2588 .Cm groupspace 2589 .Op Fl Hinp 2590 .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc 2591 .Oo Fl s Ar field Oc Ns ... 2592 .Oo Fl S Ar field Oc Ns ... 2593 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc 2594 .Ar filesystem Ns | Ns Ar snapshot 2595 .Xc 2596 Displays space consumed by, and quotas on, each group in the specified 2597 filesystem or snapshot. 2598 This subcommand is identical to 2599 .Nm zfs Cm userspace , 2600 except that the default types to display are 2601 .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . 2602 .It Xo 2603 .Nm 2604 .Cm mount 2605 .Xc 2606 Displays all ZFS file systems currently mounted. 2607 .It Xo 2608 .Nm 2609 .Cm mount 2610 .Op Fl Ov 2611 .Op Fl o Ar options 2612 .Fl a | Ar filesystem 2613 .Xc 2614 Mounts ZFS file systems. 2615 .Bl -tag -width "-O" 2616 .It Fl O 2617 Perform an overlay mount. 2618 See 2619 .Xr mount 1M 2620 for more information. 2621 .It Fl a 2622 Mount all available ZFS file systems. 2623 Invoked automatically as part of the boot process. 2624 .It Ar filesystem 2625 Mount the specified filesystem. 2626 .It Fl o Ar options 2627 An optional, comma-separated list of mount options to use temporarily for the 2628 duration of the mount. 2629 See the 2630 .Sx Temporary Mount Point Properties 2631 section for details. 2632 .It Fl v 2633 Report mount progress. 2634 .El 2635 .It Xo 2636 .Nm 2637 .Cm unmount 2638 .Op Fl f 2639 .Fl a | Ar filesystem Ns | Ns Ar mountpoint 2640 .Xc 2641 Unmounts currently mounted ZFS file systems. 2642 .Bl -tag -width "-a" 2643 .It Fl a 2644 Unmount all available ZFS file systems. 2645 Invoked automatically as part of the shutdown process. 2646 .It Ar filesystem Ns | Ns Ar mountpoint 2647 Unmount the specified filesystem. 2648 The command can also be given a path to a ZFS file system mount point on the 2649 system. 2650 .It Fl f 2651 Forcefully unmount the file system, even if it is currently in use. 2652 .El 2653 .It Xo 2654 .Nm 2655 .Cm share 2656 .Fl a | Ar filesystem 2657 .Xc 2658 Shares available ZFS file systems. 2659 .Bl -tag -width "-a" 2660 .It Fl a 2661 Share all available ZFS file systems. 2662 Invoked automatically as part of the boot process. 2663 .It Ar filesystem 2664 Share the specified filesystem according to the 2665 .Sy sharenfs 2666 and 2667 .Sy sharesmb 2668 properties. 2669 File systems are shared when the 2670 .Sy sharenfs 2671 or 2672 .Sy sharesmb 2673 property is set. 2674 .El 2675 .It Xo 2676 .Nm 2677 .Cm unshare 2678 .Fl a | Ar filesystem Ns | Ns Ar mountpoint 2679 .Xc 2680 Unshares currently shared ZFS file systems. 2681 .Bl -tag -width "-a" 2682 .It Fl a 2683 Unshare all available ZFS file systems. 2684 Invoked automatically as part of the shutdown process. 2685 .It Ar filesystem Ns | Ns Ar mountpoint 2686 Unshare the specified filesystem. 2687 The command can also be given a path to a ZFS file system shared on the system. 2688 .El 2689 .It Xo 2690 .Nm 2691 .Cm bookmark 2692 .Ar snapshot bookmark 2693 .Xc 2694 Creates a bookmark of the given snapshot. 2695 Bookmarks mark the point in time when the snapshot was created, and can be used 2696 as the incremental source for a 2697 .Nm zfs Cm send 2698 command. 2699 .Pp 2700 This feature must be enabled to be used. 2701 See 2702 .Xr zpool-features 5 2703 for details on ZFS feature flags and the 2704 .Sy bookmarks 2705 feature. 2706 .It Xo 2707 .Nm 2708 .Cm send 2709 .Op Fl DLPRcenpv 2710 .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot 2711 .Ar snapshot 2712 .Xc 2713 Creates a stream representation of the second 2714 .Ar snapshot , 2715 which is written to standard output. 2716 The output can be redirected to a file or to a different system 2717 .Po for example, using 2718 .Xr ssh 1 2719 .Pc . 2720 By default, a full stream is generated. 2721 .Bl -tag -width "-D" 2722 .It Fl D, -dedup 2723 Generate a deduplicated stream. 2724 Blocks which would have been sent multiple times in the send stream will only be 2725 sent once. 2726 The receiving system must also support this feature to receive a deduplicated 2727 stream. 2728 This flag can be used regardless of the dataset's 2729 .Sy dedup 2730 property, but performance will be much better if the filesystem uses a 2731 dedup-capable checksum 2732 .Po for example, 2733 .Sy sha256 2734 .Pc . 2735 .It Fl I Ar snapshot 2736 Generate a stream package that sends all intermediary snapshots from the first 2737 snapshot to the second snapshot. 2738 For example, 2739 .Fl I Em @a Em fs@d 2740 is similar to 2741 .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d . 2742 The incremental source may be specified as with the 2743 .Fl i 2744 option. 2745 .It Fl L, -large-block 2746 Generate a stream which may contain blocks larger than 128KB. 2747 This flag has no effect if the 2748 .Sy large_blocks 2749 pool feature is disabled, or if the 2750 .Sy recordsize 2751 property of this filesystem has never been set above 128KB. 2752 The receiving system must have the 2753 .Sy large_blocks 2754 pool feature enabled as well. 2755 See 2756 .Xr zpool-features 5 2757 for details on ZFS feature flags and the 2758 .Sy large_blocks 2759 feature. 2760 .It Fl P, -parsable 2761 Print machine-parsable verbose information about the stream package generated. 2762 .It Fl R, -replicate 2763 Generate a replication stream package, which will replicate the specified 2764 file system, and all descendent file systems, up to the named snapshot. 2765 When received, all properties, snapshots, descendent file systems, and clones 2766 are preserved. 2767 .Pp 2768 If the 2769 .Fl i 2770 or 2771 .Fl I 2772 flags are used in conjunction with the 2773 .Fl R 2774 flag, an incremental replication stream is generated. 2775 The current values of properties, and current snapshot and file system names are 2776 set when the stream is received. 2777 If the 2778 .Fl F 2779 flag is specified when this stream is received, snapshots and file systems that 2780 do not exist on the sending side are destroyed. 2781 .It Fl e, -embed 2782 Generate a more compact stream by using 2783 .Sy WRITE_EMBEDDED 2784 records for blocks which are stored more compactly on disk by the 2785 .Sy embedded_data 2786 pool feature. 2787 This flag has no effect if the 2788 .Sy embedded_data 2789 feature is disabled. 2790 The receiving system must have the 2791 .Sy embedded_data 2792 feature enabled. 2793 If the 2794 .Sy lz4_compress 2795 feature is active on the sending system, then the receiving system must have 2796 that feature enabled as well. 2797 See 2798 .Xr zpool-features 5 2799 for details on ZFS feature flags and the 2800 .Sy embedded_data 2801 feature. 2802 .It Fl c, -compressed 2803 Generate a more compact stream by using compressed WRITE records for blocks 2804 which are compressed on disk and in memory 2805 .Po see the 2806 .Sy compression 2807 property for details 2808 .Pc . 2809 If the 2810 .Sy lz4_compress 2811 feature is active on the sending system, then the receiving system must have 2812 that feature enabled as well. 2813 If the 2814 .Sy large_blocks 2815 feature is enabled on the sending system but the 2816 .Fl L 2817 option is not supplied in conjunction with 2818 .Fl c , 2819 then the data will be decompressed before sending so it can be split into 2820 smaller block sizes. 2821 .It Fl i Ar snapshot 2822 Generate an incremental stream from the first 2823 .Ar snapshot 2824 .Pq the incremental source 2825 to the second 2826 .Ar snapshot 2827 .Pq the incremental target . 2828 The incremental source can be specified as the last component of the snapshot 2829 name 2830 .Po the 2831 .Sy @ 2832 character and following 2833 .Pc 2834 and it is assumed to be from the same file system as the incremental target. 2835 .Pp 2836 If the destination is a clone, the source may be the origin snapshot, which must 2837 be fully specified 2838 .Po for example, 2839 .Em pool/fs@origin , 2840 not just 2841 .Em @origin 2842 .Pc . 2843 .It Fl n, -dryrun 2844 Do a dry-run 2845 .Pq Qq No-op 2846 send. 2847 Do not generate any actual send data. 2848 This is useful in conjunction with the 2849 .Fl v 2850 or 2851 .Fl P 2852 flags to determine what data will be sent. 2853 In this case, the verbose output will be written to standard output 2854 .Po contrast with a non-dry-run, where the stream is written to standard output 2855 and the verbose output goes to standard error 2856 .Pc . 2857 .It Fl p, -props 2858 Include the dataset's properties in the stream. 2859 This flag is implicit when 2860 .Fl R 2861 is specified. 2862 The receiving system must also support this feature. 2863 .It Fl v, -verbose 2864 Print verbose information about the stream package generated. 2865 This information includes a per-second report of how much data has been sent. 2866 .Pp 2867 The format of the stream is committed. 2868 You will be able to receive your streams on future versions of ZFS . 2869 .El 2870 .It Xo 2871 .Nm 2872 .Cm send 2873 .Op Fl Lce 2874 .Op Fl i Ar snapshot Ns | Ns Ar bookmark 2875 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 2876 .Xc 2877 Generate a send stream, which may be of a filesystem, and may be incremental 2878 from a bookmark. 2879 If the destination is a filesystem or volume, the pool must be read-only, or the 2880 filesystem must not be mounted. 2881 When the stream generated from a filesystem or volume is received, the default 2882 snapshot name will be 2883 .Qq --head-- . 2884 .Bl -tag -width "-L" 2885 .It Fl L, -large-block 2886 Generate a stream which may contain blocks larger than 128KB. 2887 This flag has no effect if the 2888 .Sy large_blocks 2889 pool feature is disabled, or if the 2890 .Sy recordsize 2891 property of this filesystem has never been set above 128KB. 2892 The receiving system must have the 2893 .Sy large_blocks 2894 pool feature enabled as well. 2895 See 2896 .Xr zpool-features 5 2897 for details on ZFS feature flags and the 2898 .Sy large_blocks 2899 feature. 2900 .It Fl c, -compressed 2901 Generate a more compact stream by using compressed WRITE records for blocks 2902 which are compressed on disk and in memory 2903 .Po see the 2904 .Sy compression 2905 property for details 2906 .Pc . 2907 If the 2908 .Sy lz4_compress 2909 feature is active on the sending system, then the receiving system must have 2910 that feature enabled as well. 2911 If the 2912 .Sy large_blocks 2913 feature is enabled on the sending system but the 2914 .Fl L 2915 option is not supplied in conjunction with 2916 .Fl c , 2917 then the data will be decompressed before sending so it can be split into 2918 smaller block sizes. 2919 .It Fl e, -embed 2920 Generate a more compact stream by using 2921 .Sy WRITE_EMBEDDED 2922 records for blocks which are stored more compactly on disk by the 2923 .Sy embedded_data 2924 pool feature. 2925 This flag has no effect if the 2926 .Sy embedded_data 2927 feature is disabled. 2928 The receiving system must have the 2929 .Sy embedded_data 2930 feature enabled. 2931 If the 2932 .Sy lz4_compress 2933 feature is active on the sending system, then the receiving system must have 2934 that feature enabled as well. 2935 See 2936 .Xr zpool-features 5 2937 for details on ZFS feature flags and the 2938 .Sy embedded_data 2939 feature. 2940 .It Fl i Ar snapshot Ns | Ns Ar bookmark 2941 Generate an incremental send stream. 2942 The incremental source must be an earlier snapshot in the destination's history. 2943 It will commonly be an earlier snapshot in the destination's file system, in 2944 which case it can be specified as the last component of the name 2945 .Po the 2946 .Sy # 2947 or 2948 .Sy @ 2949 character and following 2950 .Pc . 2951 .Pp 2952 If the incremental target is a clone, the incremental source can be the origin 2953 snapshot, or an earlier snapshot in the origin's filesystem, or the origin's 2954 origin, etc. 2955 .El 2956 .It Xo 2957 .Nm 2958 .Cm send 2959 .Op Fl Penv 2960 .Fl t 2961 .Ar receive_resume_token 2962 .Xc 2963 Creates a send stream which resumes an interrupted receive. 2964 The 2965 .Ar receive_resume_token 2966 is the value of this property on the filesystem or volume that was being 2967 received into. 2968 See the documentation for 2969 .Sy zfs receive -s 2970 for more details. 2971 .It Xo 2972 .Nm 2973 .Cm receive 2974 .Op Fl Fnsuv 2975 .Op Fl o Sy origin Ns = Ns Ar snapshot 2976 .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot 2977 .Xc 2978 .It Xo 2979 .Nm 2980 .Cm receive 2981 .Op Fl Fnsuv 2982 .Op Fl d Ns | Ns Fl e 2983 .Op Fl o Sy origin Ns = Ns Ar snapshot 2984 .Ar filesystem 2985 .Xc 2986 Creates a snapshot whose contents are as specified in the stream provided on 2987 standard input. 2988 If a full stream is received, then a new file system is created as well. 2989 Streams are created using the 2990 .Nm zfs Cm send 2991 subcommand, which by default creates a full stream. 2992 .Nm zfs Cm recv 2993 can be used as an alias for 2994 .Nm zfs Cm receive. 2995 .Pp 2996 If an incremental stream is received, then the destination file system must 2997 already exist, and its most recent snapshot must match the incremental stream's 2998 source. 2999 For 3000 .Sy zvols , 3001 the destination device link is destroyed and recreated, which means the 3002 .Sy zvol 3003 cannot be accessed during the 3004 .Cm receive 3005 operation. 3006 .Pp 3007 When a snapshot replication package stream that is generated by using the 3008 .Nm zfs Cm send Fl R 3009 command is received, any snapshots that do not exist on the sending location are 3010 destroyed by using the 3011 .Nm zfs Cm destroy Fl d 3012 command. 3013 .Pp 3014 The name of the snapshot 3015 .Pq and file system, if a full stream is received 3016 that this subcommand creates depends on the argument type and the use of the 3017 .Fl d 3018 or 3019 .Fl e 3020 options. 3021 .Pp 3022 If the argument is a snapshot name, the specified 3023 .Ar snapshot 3024 is created. 3025 If the argument is a file system or volume name, a snapshot with the same name 3026 as the sent snapshot is created within the specified 3027 .Ar filesystem 3028 or 3029 .Ar volume . 3030 If neither of the 3031 .Fl d 3032 or 3033 .Fl e 3034 options are specified, the provided target snapshot name is used exactly as 3035 provided. 3036 .Pp 3037 The 3038 .Fl d 3039 and 3040 .Fl e 3041 options cause the file system name of the target snapshot to be determined by 3042 appending a portion of the sent snapshot's name to the specified target 3043 .Ar filesystem . 3044 If the 3045 .Fl d 3046 option is specified, all but the first element of the sent snapshot's file 3047 system path 3048 .Pq usually the pool name 3049 is used and any required intermediate file systems within the specified one are 3050 created. 3051 If the 3052 .Fl e 3053 option is specified, then only the last element of the sent snapshot's file 3054 system name 3055 .Pq i.e. the name of the source file system itself 3056 is used as the target file system name. 3057 .Bl -tag -width "-F" 3058 .It Fl F 3059 Force a rollback of the file system to the most recent snapshot before 3060 performing the receive operation. 3061 If receiving an incremental replication stream 3062 .Po for example, one generated by 3063 .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I 3064 .Pc , 3065 destroy snapshots and file systems that do not exist on the sending side. 3066 .It Fl d 3067 Discard the first element of the sent snapshot's file system name, using the 3068 remaining elements to determine the name of the target file system for the new 3069 snapshot as described in the paragraph above. 3070 .It Fl e 3071 Discard all but the last element of the sent snapshot's file system name, using 3072 that element to determine the name of the target file system for the new 3073 snapshot as described in the paragraph above. 3074 .It Fl n 3075 Do not actually receive the stream. 3076 This can be useful in conjunction with the 3077 .Fl v 3078 option to verify the name the receive operation would use. 3079 .It Fl o Sy origin Ns = Ns Ar snapshot 3080 Forces the stream to be received as a clone of the given snapshot. 3081 If the stream is a full send stream, this will create the filesystem 3082 described by the stream as a clone of the specified snapshot. 3083 Which snapshot was specified will not affect the success or failure of the 3084 receive, as long as the snapshot does exist. 3085 If the stream is an incremental send stream, all the normal verification will be 3086 performed. 3087 .It Fl u 3088 File system that is associated with the received stream is not mounted. 3089 .It Fl v 3090 Print verbose information about the stream and the time required to perform the 3091 receive operation. 3092 .It Fl s 3093 If the receive is interrupted, save the partially received state, rather 3094 than deleting it. 3095 Interruption may be due to premature termination of the stream 3096 .Po e.g. due to network failure or failure of the remote system 3097 if the stream is being read over a network connection 3098 .Pc , 3099 a checksum error in the stream, termination of the 3100 .Nm zfs Cm receive 3101 process, or unclean shutdown of the system. 3102 .Pp 3103 The receive can be resumed with a stream generated by 3104 .Nm zfs Cm send Fl t Ar token , 3105 where the 3106 .Ar token 3107 is the value of the 3108 .Sy receive_resume_token 3109 property of the filesystem or volume which is received into. 3110 .Pp 3111 To use this flag, the storage pool must have the 3112 .Sy extensible_dataset 3113 feature enabled. 3114 See 3115 .Xr zpool-features 5 3116 for details on ZFS feature flags. 3117 .El 3118 .It Xo 3119 .Nm 3120 .Cm receive 3121 .Fl A 3122 .Ar filesystem Ns | Ns Ar volume 3123 .Xc 3124 Abort an interrupted 3125 .Nm zfs Cm receive Fl s , 3126 deleting its saved partially received state. 3127 .It Xo 3128 .Nm 3129 .Cm allow 3130 .Ar filesystem Ns | Ns Ar volume 3131 .Xc 3132 Displays permissions that have been delegated on the specified filesystem or 3133 volume. 3134 See the other forms of 3135 .Nm zfs Cm allow 3136 for more information. 3137 .It Xo 3138 .Nm 3139 .Cm allow 3140 .Op Fl dglu 3141 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 3142 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3143 .Ar setname Oc Ns ... 3144 .Ar filesystem Ns | Ns Ar volume 3145 .br 3146 .Nm 3147 .Cm allow 3148 .Op Fl dl 3149 .Fl e Ns | Ns Sy everyone 3150 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3151 .Ar setname Oc Ns ... 3152 .Ar filesystem Ns | Ns Ar volume 3153 .Xc 3154 Delegates ZFS administration permission for the file systems to non-privileged 3155 users. 3156 .Bl -tag -width "-d" 3157 .It Fl d 3158 Allow only for the descendent file systems. 3159 .It Fl e Ns | Ns Sy everyone 3160 Specifies that the permissions be delegated to everyone. 3161 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ... 3162 Explicitly specify that permissions are delegated to the group. 3163 .It Fl l 3164 Allow 3165 .Qq locally 3166 only for the specified file system. 3167 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... 3168 Explicitly specify that permissions are delegated to the user. 3169 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 3170 Specifies to whom the permissions are delegated. 3171 Multiple entities can be specified as a comma-separated list. 3172 If neither of the 3173 .Fl gu 3174 options are specified, then the argument is interpreted preferentially as the 3175 keyword 3176 .Sy everyone , 3177 then as a user name, and lastly as a group name. 3178 To specify a user or group named 3179 .Qq everyone , 3180 use the 3181 .Fl g 3182 or 3183 .Fl u 3184 options. 3185 To specify a group with the same name as a user, use the 3186 .Fl g 3187 options. 3188 .It Xo 3189 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3190 .Ar setname Oc Ns ... 3191 .Xc 3192 The permissions to delegate. 3193 Multiple permissions may be specified as a comma-separated list. 3194 Permission names are the same as ZFS subcommand and property names. 3195 See the property list below. 3196 Property set names, which begin with 3197 .Sy @ , 3198 may be specified. 3199 See the 3200 .Fl s 3201 form below for details. 3202 .El 3203 .Pp 3204 If neither of the 3205 .Fl dl 3206 options are specified, or both are, then the permissions are allowed for the 3207 file system or volume, and all of its descendents. 3208 .Pp 3209 Permissions are generally the ability to use a ZFS subcommand or change a ZFS 3210 property. 3211 The following permissions are available: 3212 .Bd -literal 3213 NAME TYPE NOTES 3214 allow subcommand Must also have the permission that is 3215 being allowed 3216 clone subcommand Must also have the 'create' ability and 3217 'mount' ability in the origin file system 3218 create subcommand Must also have the 'mount' ability 3219 destroy subcommand Must also have the 'mount' ability 3220 diff subcommand Allows lookup of paths within a dataset 3221 given an object number, and the ability 3222 to create snapshots necessary to 3223 'zfs diff'. 3224 mount subcommand Allows mount/umount of ZFS datasets 3225 promote subcommand Must also have the 'mount' and 'promote' 3226 ability in the origin file system 3227 receive subcommand Must also have the 'mount' and 'create' 3228 ability 3229 rename subcommand Must also have the 'mount' and 'create' 3230 ability in the new parent 3231 rollback subcommand Must also have the 'mount' ability 3232 send subcommand 3233 share subcommand Allows sharing file systems over NFS 3234 or SMB protocols 3235 snapshot subcommand Must also have the 'mount' ability 3236 3237 groupquota other Allows accessing any groupquota@... 3238 property 3239 groupused other Allows reading any groupused@... property 3240 userprop other Allows changing any user property 3241 userquota other Allows accessing any userquota@... 3242 property 3243 userused other Allows reading any userused@... property 3244 3245 aclinherit property 3246 aclmode property 3247 atime property 3248 canmount property 3249 casesensitivity property 3250 checksum property 3251 compression property 3252 copies property 3253 devices property 3254 exec property 3255 filesystem_limit property 3256 mountpoint property 3257 nbmand property 3258 normalization property 3259 primarycache property 3260 quota property 3261 readonly property 3262 recordsize property 3263 refquota property 3264 refreservation property 3265 reservation property 3266 secondarycache property 3267 setuid property 3268 sharenfs property 3269 sharesmb property 3270 snapdir property 3271 snapshot_limit property 3272 utf8only property 3273 version property 3274 volblocksize property 3275 volsize property 3276 vscan property 3277 xattr property 3278 zoned property 3279 .Ed 3280 .It Xo 3281 .Nm 3282 .Cm allow 3283 .Fl c 3284 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3285 .Ar setname Oc Ns ... 3286 .Ar filesystem Ns | Ns Ar volume 3287 .Xc 3288 Sets 3289 .Qq create time 3290 permissions. 3291 These permissions are granted 3292 .Pq locally 3293 to the creator of any newly-created descendent file system. 3294 .It Xo 3295 .Nm 3296 .Cm allow 3297 .Fl s No @ Ns Ar setname 3298 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3299 .Ar setname Oc Ns ... 3300 .Ar filesystem Ns | Ns Ar volume 3301 .Xc 3302 Defines or adds permissions to a permission set. 3303 The set can be used by other 3304 .Nm zfs Cm allow 3305 commands for the specified file system and its descendents. 3306 Sets are evaluated dynamically, so changes to a set are immediately reflected. 3307 Permission sets follow the same naming restrictions as ZFS file systems, but the 3308 name must begin with 3309 .Sy @ , 3310 and can be no more than 64 characters long. 3311 .It Xo 3312 .Nm 3313 .Cm unallow 3314 .Op Fl dglru 3315 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... 3316 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3317 .Ar setname Oc Ns ... Oc 3318 .Ar filesystem Ns | Ns Ar volume 3319 .br 3320 .Nm 3321 .Cm unallow 3322 .Op Fl dlr 3323 .Fl e Ns | Ns Sy everyone 3324 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3325 .Ar setname Oc Ns ... Oc 3326 .Ar filesystem Ns | Ns Ar volume 3327 .br 3328 .Nm 3329 .Cm unallow 3330 .Op Fl r 3331 .Fl c 3332 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3333 .Ar setname Oc Ns ... Oc 3334 .Ar filesystem Ns | Ns Ar volume 3335 .Xc 3336 Removes permissions that were granted with the 3337 .Nm zfs Cm allow 3338 command. 3339 No permissions are explicitly denied, so other permissions granted are still in 3340 effect. 3341 For example, if the permission is granted by an ancestor. 3342 If no permissions are specified, then all permissions for the specified 3343 .Ar user , 3344 .Ar group , 3345 or 3346 .Sy everyone 3347 are removed. 3348 Specifying 3349 .Sy everyone 3350 .Po or using the 3351 .Fl e 3352 option 3353 .Pc 3354 only removes the permissions that were granted to everyone, not all permissions 3355 for every user and group. 3356 See the 3357 .Nm zfs Cm allow 3358 command for a description of the 3359 .Fl ldugec 3360 options. 3361 .Bl -tag -width "-r" 3362 .It Fl r 3363 Recursively remove the permissions from this file system and all descendents. 3364 .El 3365 .It Xo 3366 .Nm 3367 .Cm unallow 3368 .Op Fl r 3369 .Fl s No @ Ns Ar setname 3370 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns 3371 .Ar setname Oc Ns ... Oc 3372 .Ar filesystem Ns | Ns Ar volume 3373 .Xc 3374 Removes permissions from a permission set. 3375 If no permissions are specified, then all permissions are removed, thus removing 3376 the set entirely. 3377 .It Xo 3378 .Nm 3379 .Cm hold 3380 .Op Fl r 3381 .Ar tag Ar snapshot Ns ... 3382 .Xc 3383 Adds a single reference, named with the 3384 .Ar tag 3385 argument, to the specified snapshot or snapshots. 3386 Each snapshot has its own tag namespace, and tags must be unique within that 3387 space. 3388 .Pp 3389 If a hold exists on a snapshot, attempts to destroy that snapshot by using the 3390 .Nm zfs Cm destroy 3391 command return 3392 .Er EBUSY . 3393 .Bl -tag -width "-r" 3394 .It Fl r 3395 Specifies that a hold with the given tag is applied recursively to the snapshots 3396 of all descendent file systems. 3397 .El 3398 .It Xo 3399 .Nm 3400 .Cm holds 3401 .Op Fl r 3402 .Ar snapshot Ns ... 3403 .Xc 3404 Lists all existing user references for the given snapshot or snapshots. 3405 .Bl -tag -width "-r" 3406 .It Fl r 3407 Lists the holds that are set on the named descendent snapshots, in addition to 3408 listing the holds on the named snapshot. 3409 .El 3410 .It Xo 3411 .Nm 3412 .Cm release 3413 .Op Fl r 3414 .Ar tag Ar snapshot Ns ... 3415 .Xc 3416 Removes a single reference, named with the 3417 .Ar tag 3418 argument, from the specified snapshot or snapshots. 3419 The tag must already exist for each snapshot. 3420 If a hold exists on a snapshot, attempts to destroy that snapshot by using the 3421 .Nm zfs Cm destroy 3422 command return 3423 .Er EBUSY . 3424 .Bl -tag -width "-r" 3425 .It Fl r 3426 Recursively releases a hold with the given tag on the snapshots of all 3427 descendent file systems. 3428 .El 3429 .It Xo 3430 .Nm 3431 .Cm diff 3432 .Op Fl FHt 3433 .Ar snapshot Ar snapshot Ns | Ns Ar filesystem 3434 .Xc 3435 Display the difference between a snapshot of a given filesystem and another 3436 snapshot of that filesystem from a later time or the current contents of the 3437 filesystem. 3438 The first column is a character indicating the type of change, the other columns 3439 indicate pathname, new pathname 3440 .Pq in case of rename , 3441 change in link count, and optionally file type and/or change time. 3442 The types of change are: 3443 .Bd -literal 3444 - The path has been removed 3445 + The path has been created 3446 M The path has been modified 3447 R The path has been renamed 3448 .Ed 3449 .Bl -tag -width "-F" 3450 .It Fl F 3451 Display an indication of the type of file, in a manner similar to the 3452 .Fl 3453 option of 3454 .Xr ls 1 . 3455 .Bd -literal 3456 B Block device 3457 C Character device 3458 / Directory 3459 > Door 3460 | Named pipe 3461 @ Symbolic link 3462 P Event port 3463 = Socket 3464 F Regular file 3465 .Ed 3466 .It Fl H 3467 Give more parsable tab-separated output, without header lines and without 3468 arrows. 3469 .It Fl t 3470 Display the path's inode change time as the first column of output. 3471 .El 3472 .It Xo 3473 .Nm 3474 .Cm program 3475 .Op Fl n 3476 .Op Fl t Ar timeout 3477 .Op Fl m Ar memory_limit 3478 .Ar pool script 3479 .Op Ar arg1 No ... 3480 .Xc 3481 Executes 3482 .Ar script 3483 as a ZFS channel program on 3484 .Ar pool . 3485 The ZFS channel 3486 program interface allows ZFS administrative operations to be run 3487 programmatically via a Lua script. 3488 The entire script is executed atomically, with no other administrative 3489 operations taking effect concurrently. 3490 A library of ZFS calls is made available to channel program scripts. 3491 Channel programs may only be run with root privileges. 3492 .sp 3493 For full documentation of the ZFS channel program interface, see the manual 3494 page for 3495 .Bl -tag -width "" 3496 .It Fl n 3497 Executes a read-only channel program, which runs faster. 3498 The program cannot change on-disk state by calling functions from 3499 the zfs.sync submodule. 3500 The program can be used to gather information such as properties and 3501 determining if changes would succeed (zfs.check.*). 3502 Without this flag, all pending changes must be synced to disk before 3503 a channel program can complete. 3504 .It Fl t Ar timeout 3505 Execution time limit, in milliseconds. 3506 If a channel program executes for longer than the provided timeout, it will 3507 be stopped and an error will be returned. 3508 The default timeout is 1000 ms, and can be set to a maximum of 10000 ms. 3509 .It Fl m Ar memory-limit 3510 Memory limit, in bytes. 3511 If a channel program attempts to allocate more memory than the given limit, 3512 it will be stopped and an error returned. 3513 The default memory limit is 10 MB, and can be set to a maximum of 100 MB. 3514 .sp 3515 All remaining argument strings are passed directly to the channel program as 3516 arguments. 3517 See 3518 .Xr zfs-program 1M 3519 for more information. 3520 .El 3521 .El 3522 .Sh EXIT STATUS 3523 The 3524 .Nm 3525 utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line 3526 options were specified. 3527 .Sh EXAMPLES 3528 .Bl -tag -width "" 3529 .It Sy Example 1 No Creating a ZFS File System Hierarchy 3530 The following commands create a file system named 3531 .Em pool/home 3532 and a file system named 3533 .Em pool/home/bob . 3534 The mount point 3535 .Pa /export/home 3536 is set for the parent file system, and is automatically inherited by the child 3537 file system. 3538 .Bd -literal 3539 # zfs create pool/home 3540 # zfs set mountpoint=/export/home pool/home 3541 # zfs create pool/home/bob 3542 .Ed 3543 .It Sy Example 2 No Creating a ZFS Snapshot 3544 The following command creates a snapshot named 3545 .Sy yesterday . 3546 This snapshot is mounted on demand in the 3547 .Pa .zfs/snapshot 3548 directory at the root of the 3549 .Em pool/home/bob 3550 file system. 3551 .Bd -literal 3552 # zfs snapshot pool/home/bob@yesterday 3553 .Ed 3554 .It Sy Example 3 No Creating and Destroying Multiple Snapshots 3555 The following command creates snapshots named 3556 .Sy yesterday 3557 of 3558 .Em pool/home 3559 and all of its descendent file systems. 3560 Each snapshot is mounted on demand in the 3561 .Pa .zfs/snapshot 3562 directory at the root of its file system. 3563 The second command destroys the newly created snapshots. 3564 .Bd -literal 3565 # zfs snapshot -r pool/home@yesterday 3566 # zfs destroy -r pool/home@yesterday 3567 .Ed 3568 .It Sy Example 4 No Disabling and Enabling File System Compression 3569 The following command disables the 3570 .Sy compression 3571 property for all file systems under 3572 .Em pool/home . 3573 The next command explicitly enables 3574 .Sy compression 3575 for 3576 .Em pool/home/anne . 3577 .Bd -literal 3578 # zfs set compression=off pool/home 3579 # zfs set compression=on pool/home/anne 3580 .Ed 3581 .It Sy Example 5 No Listing ZFS Datasets 3582 The following command lists all active file systems and volumes in the system. 3583 Snapshots are displayed if the 3584 .Sy listsnaps 3585 property is 3586 .Sy on . 3587 The default is 3588 .Sy off . 3589 See 3590 .Xr zpool 1M 3591 for more information on pool properties. 3592 .Bd -literal 3593 # zfs list 3594 NAME USED AVAIL REFER MOUNTPOINT 3595 pool 450K 457G 18K /pool 3596 pool/home 315K 457G 21K /export/home 3597 pool/home/anne 18K 457G 18K /export/home/anne 3598 pool/home/bob 276K 457G 276K /export/home/bob 3599 .Ed 3600 .It Sy Example 6 No Setting a Quota on a ZFS File System 3601 The following command sets a quota of 50 Gbytes for 3602 .Em pool/home/bob . 3603 .Bd -literal 3604 # zfs set quota=50G pool/home/bob 3605 .Ed 3606 .It Sy Example 7 No Listing ZFS Properties 3607 The following command lists all properties for 3608 .Em pool/home/bob . 3609 .Bd -literal 3610 # zfs get all pool/home/bob 3611 NAME PROPERTY VALUE SOURCE 3612 pool/home/bob type filesystem - 3613 pool/home/bob creation Tue Jul 21 15:53 2009 - 3614 pool/home/bob used 21K - 3615 pool/home/bob available 20.0G - 3616 pool/home/bob referenced 21K - 3617 pool/home/bob compressratio 1.00x - 3618 pool/home/bob mounted yes - 3619 pool/home/bob quota 20G local 3620 pool/home/bob reservation none default 3621 pool/home/bob recordsize 128K default 3622 pool/home/bob mountpoint /pool/home/bob default 3623 pool/home/bob sharenfs off default 3624 pool/home/bob checksum on default 3625 pool/home/bob compression on local 3626 pool/home/bob atime on default 3627 pool/home/bob devices on default 3628 pool/home/bob exec on default 3629 pool/home/bob setuid on default 3630 pool/home/bob readonly off default 3631 pool/home/bob zoned off default 3632 pool/home/bob snapdir hidden default 3633 pool/home/bob aclmode discard default 3634 pool/home/bob aclinherit restricted default 3635 pool/home/bob canmount on default 3636 pool/home/bob xattr on default 3637 pool/home/bob copies 1 default 3638 pool/home/bob version 4 - 3639 pool/home/bob utf8only off - 3640 pool/home/bob normalization none - 3641 pool/home/bob casesensitivity sensitive - 3642 pool/home/bob vscan off default 3643 pool/home/bob nbmand off default 3644 pool/home/bob sharesmb off default 3645 pool/home/bob refquota none default 3646 pool/home/bob refreservation none default 3647 pool/home/bob primarycache all default 3648 pool/home/bob secondarycache all default 3649 pool/home/bob usedbysnapshots 0 - 3650 pool/home/bob usedbydataset 21K - 3651 pool/home/bob usedbychildren 0 - 3652 pool/home/bob usedbyrefreservation 0 - 3653 .Ed 3654 .Pp 3655 The following command gets a single property value. 3656 .Bd -literal 3657 # zfs get -H -o value compression pool/home/bob 3658 on 3659 .Ed 3660 The following command lists all properties with local settings for 3661 .Em pool/home/bob . 3662 .Bd -literal 3663 # zfs get -r -s local -o name,property,value all pool/home/bob 3664 NAME PROPERTY VALUE 3665 pool/home/bob quota 20G 3666 pool/home/bob compression on 3667 .Ed 3668 .It Sy Example 8 No Rolling Back a ZFS File System 3669 The following command reverts the contents of 3670 .Em pool/home/anne 3671 to the snapshot named 3672 .Sy yesterday , 3673 deleting all intermediate snapshots. 3674 .Bd -literal 3675 # zfs rollback -r pool/home/anne@yesterday 3676 .Ed 3677 .It Sy Example 9 No Creating a ZFS Clone 3678 The following command creates a writable file system whose initial contents are 3679 the same as 3680 .Em pool/home/bob@yesterday . 3681 .Bd -literal 3682 # zfs clone pool/home/bob@yesterday pool/clone 3683 .Ed 3684 .It Sy Example 10 No Promoting a ZFS Clone 3685 The following commands illustrate how to test out changes to a file system, and 3686 then replace the original file system with the changed one, using clones, clone 3687 promotion, and renaming: 3688 .Bd -literal 3689 # zfs create pool/project/production 3690 populate /pool/project/production with data 3691 # zfs snapshot pool/project/production@today 3692 # zfs clone pool/project/production@today pool/project/beta 3693 make changes to /pool/project/beta and test them 3694 # zfs promote pool/project/beta 3695 # zfs rename pool/project/production pool/project/legacy 3696 # zfs rename pool/project/beta pool/project/production 3697 once the legacy version is no longer needed, it can be destroyed 3698 # zfs destroy pool/project/legacy 3699 .Ed 3700 .It Sy Example 11 No Inheriting ZFS Properties 3701 The following command causes 3702 .Em pool/home/bob 3703 and 3704 .Em pool/home/anne 3705 to inherit the 3706 .Sy checksum 3707 property from their parent. 3708 .Bd -literal 3709 # zfs inherit checksum pool/home/bob pool/home/anne 3710 .Ed 3711 .It Sy Example 12 No Remotely Replicating ZFS Data 3712 The following commands send a full stream and then an incremental stream to a 3713 remote machine, restoring them into 3714 .Em poolB/received/fs@a 3715 and 3716 .Em poolB/received/fs@b , 3717 respectively. 3718 .Em poolB 3719 must contain the file system 3720 .Em poolB/received , 3721 and must not initially contain 3722 .Em poolB/received/fs . 3723 .Bd -literal 3724 # zfs send pool/fs@a | \e 3725 ssh host zfs receive poolB/received/fs@a 3726 # zfs send -i a pool/fs@b | \e 3727 ssh host zfs receive poolB/received/fs 3728 .Ed 3729 .It Sy Example 13 No Using the zfs receive -d Option 3730 The following command sends a full stream of 3731 .Em poolA/fsA/fsB@snap 3732 to a remote machine, receiving it into 3733 .Em poolB/received/fsA/fsB@snap . 3734 The 3735 .Em fsA/fsB@snap 3736 portion of the received snapshot's name is determined from the name of the sent 3737 snapshot. 3738 .Em poolB 3739 must contain the file system 3740 .Em poolB/received . 3741 If 3742 .Em poolB/received/fsA 3743 does not exist, it is created as an empty file system. 3744 .Bd -literal 3745 # zfs send poolA/fsA/fsB@snap | \e 3746 ssh host zfs receive -d poolB/received 3747 .Ed 3748 .It Sy Example 14 No Setting User Properties 3749 The following example sets the user-defined 3750 .Sy com.example:department 3751 property for a dataset. 3752 .Bd -literal 3753 # zfs set com.example:department=12345 tank/accounting 3754 .Ed 3755 .It Sy Example 15 No Performing a Rolling Snapshot 3756 The following example shows how to maintain a history of snapshots with a 3757 consistent naming scheme. 3758 To keep a week's worth of snapshots, the user destroys the oldest snapshot, 3759 renames the remaining snapshots, and then creates a new snapshot, as follows: 3760 .Bd -literal 3761 # zfs destroy -r pool/users@7daysago 3762 # zfs rename -r pool/users@6daysago @7daysago 3763 # zfs rename -r pool/users@5daysago @6daysago 3764 # zfs rename -r pool/users@yesterday @5daysago 3765 # zfs rename -r pool/users@yesterday @4daysago 3766 # zfs rename -r pool/users@yesterday @3daysago 3767 # zfs rename -r pool/users@yesterday @2daysago 3768 # zfs rename -r pool/users@today @yesterday 3769 # zfs snapshot -r pool/users@today 3770 .Ed 3771 .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System 3772 The following commands show how to set 3773 .Sy sharenfs 3774 property options to enable 3775 .Sy rw 3776 access for a set of 3777 .Sy IP 3778 addresses and to enable root access for system 3779 .Sy neo 3780 on the 3781 .Em tank/home 3782 file system. 3783 .Bd -literal 3784 # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home 3785 .Ed 3786 .Pp 3787 If you are using 3788 .Sy DNS 3789 for host name resolution, specify the fully qualified hostname. 3790 .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset 3791 The following example shows how to set permissions so that user 3792 .Sy cindys 3793 can create, destroy, mount, and take snapshots on 3794 .Em tank/cindys . 3795 The permissions on 3796 .Em tank/cindys 3797 are also displayed. 3798 .Bd -literal 3799 # zfs allow cindys create,destroy,mount,snapshot tank/cindys 3800 # zfs allow tank/cindys 3801 ---- Permissions on tank/cindys -------------------------------------- 3802 Local+Descendent permissions: 3803 user cindys create,destroy,mount,snapshot 3804 .Ed 3805 .Pp 3806 Because the 3807 .Em tank/cindys 3808 mount point permission is set to 755 by default, user 3809 .Sy cindys 3810 will be unable to mount file systems under 3811 .Em tank/cindys . 3812 Add an ACE similar to the following syntax to provide mount point access: 3813 .Bd -literal 3814 # chmod A+user:cindys:add_subdirectory:allow /tank/cindys 3815 .Ed 3816 .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset 3817 The following example shows how to grant anyone in the group 3818 .Sy staff 3819 to create file systems in 3820 .Em tank/users . 3821 This syntax also allows staff members to destroy their own file systems, but not 3822 destroy anyone else's file system. 3823 The permissions on 3824 .Em tank/users 3825 are also displayed. 3826 .Bd -literal 3827 # zfs allow staff create,mount tank/users 3828 # zfs allow -c destroy tank/users 3829 # zfs allow tank/users 3830 ---- Permissions on tank/users --------------------------------------- 3831 Permission sets: 3832 destroy 3833 Local+Descendent permissions: 3834 group staff create,mount 3835 .Ed 3836 .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset 3837 The following example shows how to define and grant a permission set on the 3838 .Em tank/users 3839 file system. 3840 The permissions on 3841 .Em tank/users 3842 are also displayed. 3843 .Bd -literal 3844 # zfs allow -s @pset create,destroy,snapshot,mount tank/users 3845 # zfs allow staff @pset tank/users 3846 # zfs allow tank/users 3847 ---- Permissions on tank/users --------------------------------------- 3848 Permission sets: 3849 @pset create,destroy,mount,snapshot 3850 Local+Descendent permissions: 3851 group staff @pset 3852 .Ed 3853 .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset 3854 The following example shows to grant the ability to set quotas and reservations 3855 on the 3856 .Em users/home 3857 file system. 3858 The permissions on 3859 .Em users/home 3860 are also displayed. 3861 .Bd -literal 3862 # zfs allow cindys quota,reservation users/home 3863 # zfs allow users/home 3864 ---- Permissions on users/home --------------------------------------- 3865 Local+Descendent permissions: 3866 user cindys quota,reservation 3867 cindys% zfs set quota=10G users/home/marks 3868 cindys% zfs get quota users/home/marks 3869 NAME PROPERTY VALUE SOURCE 3870 users/home/marks quota 10G local 3871 .Ed 3872 .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset 3873 The following example shows how to remove the snapshot permission from the 3874 .Sy staff 3875 group on the 3876 .Em tank/users 3877 file system. 3878 The permissions on 3879 .Em tank/users 3880 are also displayed. 3881 .Bd -literal 3882 # zfs unallow staff snapshot tank/users 3883 # zfs allow tank/users 3884 ---- Permissions on tank/users --------------------------------------- 3885 Permission sets: 3886 @pset create,destroy,mount,snapshot 3887 Local+Descendent permissions: 3888 group staff @pset 3889 .Ed 3890 .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset 3891 The following example shows how to see what has changed between a prior 3892 snapshot of a ZFS dataset and its current state. 3893 The 3894 .Fl F 3895 option is used to indicate type information for the files affected. 3896 .Bd -literal 3897 # zfs diff -F tank/test@before tank/test 3898 M / /tank/test/ 3899 M F /tank/test/linked (+1) 3900 R F /tank/test/oldname -> /tank/test/newname 3901 - F /tank/test/deleted 3902 + F /tank/test/created 3903 M F /tank/test/modified 3904 .Ed 3905 .El 3906 .Sh INTERFACE STABILITY 3907 .Sy Committed . 3908 .Sh SEE ALSO 3909 .Xr gzip 1 , 3910 .Xr ssh 1 , 3911 .Xr mount 1M , 3912 .Xr share 1M , 3913 .Xr sharemgr 1M , 3914 .Xr unshare 1M , 3915 .Xr zonecfg 1M , 3916 .Xr zpool 1M , 3917 .Xr chmod 2 , 3918 .Xr stat 2 , 3919 .Xr write 2 , 3920 .Xr fsync 3C , 3921 .Xr dfstab 4 , 3922 .Xr acl 5 , 3923 .Xr attributes 5