man/man8/zfs.8

   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 https://opensource.org/licenses/CDDL-1.0.
  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 .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
  22 .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
  23 .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
  24 .\" Copyright (c) 2011, Pawel Jakub Dawidek <pjd@FreeBSD.org>
  25 .\" Copyright (c) 2012, Glen Barber <gjb@FreeBSD.org>
  26 .\" Copyright (c) 2012, Bryan Drewery <bdrewery@FreeBSD.org>
  27 .\" Copyright (c) 2013, Steven Hartland <smh@FreeBSD.org>
  28 .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
  29 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
  30 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
  31 .\" Copyright (c) 2014 Integros [integros.com]
  32 .\" Copyright (c) 2014, Xin LI <delphij@FreeBSD.org>
  33 .\" Copyright (c) 2014-2015, The FreeBSD Foundation, All Rights Reserved.
  34 .\" Copyright (c) 2016 Nexenta Systems, Inc. All Rights Reserved.
  35 .\" Copyright 2019 Richard Laager. All rights reserved.
  36 .\" Copyright 2018 Nexenta Systems, Inc.
  37 .\" Copyright 2019 Joyent, Inc.
  38 .\"
  39 .Dd May 12, 2022
  40 .Dt ZFS 8
  41 .Os
  42 .
  43 .Sh NAME
  44 .Nm zfs
  45 .Nd configure ZFS datasets
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Fl ?V
  49 .Nm
  50 .Cm version
  51 .Nm
  52 .Cm subcommand
  53 .Op Ar arguments
  54 .
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 command configures ZFS datasets within a ZFS storage pool, as described in
  59 .Xr zpool 8 .
  60 A dataset is identified by a unique path within the ZFS namespace:
  61 .Pp
  62 .D1 Ar pool Ns Oo Sy / Ns Ar component Oc Ns Sy / Ns Ar component
  63 .Pp
  64 for example:
  65 .Pp
  66 .Dl rpool/var/log
  67 .Pp
  68 The maximum length of a dataset name is
  69 .Sy ZFS_MAX_DATASET_NAME_LEN No - 1
  70 ASCII characters (currently 255) satisfying
  71 .Sy [A-Za-z_.:/ -] .
  72 Additionally snapshots are allowed to contain a single
  73 .Sy @
  74 character, while bookmarks are allowed to contain a single
  75 .Sy #
  76 character.
  77 .Sy /
  78 is used as separator between components.
  79 The maximum amount of nesting allowed in a path is
  80 .Sy zfs_max_dataset_nesting
  81 levels deep.
  82 ZFS tunables
  83 .Pq Sy zfs_*
  84 are explained in
  85 .Xr zfs 4 .
  86 .Pp
  87 A dataset can be one of the following:
  88 .Bl -tag -offset Ds -width "file system"
  89 .It Sy file system
  90 Can be mounted within the standard system namespace and behaves like other file
  91 systems.
  92 While ZFS file systems are designed to be POSIX-compliant, known issues exist
  93 that prevent compliance in some cases.
  94 Applications that depend on standards conformance might fail due to non-standard
  95 behavior when checking file system free space.
  96 .It Sy volume
  97 A logical volume exported as a raw or block device.
  98 This type of dataset should only be used when a block device is required.
  99 File systems are typically used in most environments.
 100 .It Sy snapshot
 101 A read-only version of a file system or volume at a given point in time.
 102 It is specified as
 103 .Ar filesystem Ns @ Ns Ar name
 104 or
 105 .Ar volume Ns @ Ns Ar name .
 106 .It Sy bookmark
 107 Much like a
 108 .Sy snapshot ,
 109 but without the hold on on-disk data.
 110 It can be used as the source of a send (but not for a receive).
 111 It is specified as
 112 .Ar filesystem Ns # Ns Ar name
 113 or
 114 .Ar volume Ns # Ns Ar name .
 115 .El
 116 .Pp
 117 See
 118 .Xr zfsconcepts 7
 119 for details.
 120 .
 121 .Ss Properties
 122 Properties are divided into two types: native properties and user-defined
 123 .Pq or Qq user
 124 properties.
 125 Native properties either export internal statistics or control ZFS behavior.
 126 In addition, native properties are either editable or read-only.
 127 User properties have no effect on ZFS behavior, but you can use them to annotate
 128 datasets in a way that is meaningful in your environment.
 129 For more information about properties, see
 130 .Xr zfsprops 7 .
 131 .
 132 .Ss Encryption
 133 Enabling the
 134 .Sy encryption
 135 feature allows for the creation of encrypted filesystems and volumes.
 136 ZFS will encrypt file and zvol data, file attributes, ACLs, permission bits,
 137 directory listings, FUID mappings, and
 138 .Sy userused Ns / Ns Sy groupused Ns / Ns Sy projectused
 139 data.
 140 For an overview of encryption, see
 141 .Xr zfs-load-key 8 .
 142 .
 143 .Sh SUBCOMMANDS
 144 All subcommands that modify state are logged persistently to the pool in their
 145 original form.
 146 .Bl -tag -width ""
 147 .It Nm Fl ?
 148 Displays a help message.
 149 .It Xo
 150 .Nm
 151 .Fl V , -version
 152 .Xc
 153 .It Xo
 154 .Nm
 155 .Cm version
 156 .Xc
 157 Displays the software version of the
 158 .Nm
 159 userland utility and the zfs kernel module.
 160 .El
 161 .
 162 .Ss Dataset Management
 163 .Bl -tag -width ""
 164 .It Xr zfs-list 8
 165 Lists the property information for the given datasets in tabular form.
 166 .It Xr zfs-create 8
 167 Creates a new ZFS file system or volume.
 168 .It Xr zfs-destroy 8
 169 Destroys the given dataset(s), snapshot(s), or bookmark.
 170 .It Xr zfs-rename 8
 171 Renames the given dataset (filesystem or snapshot).
 172 .It Xr zfs-upgrade 8
 173 Manage upgrading the on-disk version of filesystems.
 174 .El
 175 .
 176 .Ss Snapshots
 177 .Bl -tag -width ""
 178 .It Xr zfs-snapshot 8
 179 Creates snapshots with the given names.
 180 .It Xr zfs-rollback 8
 181 Roll back the given dataset to a previous snapshot.
 182 .It Xr zfs-hold 8 Ns / Ns Xr zfs-release 8
 183 Add or remove a hold reference to the specified snapshot or snapshots.
 184 If a hold exists on a snapshot, attempts to destroy that snapshot by using the
 185 .Nm zfs Cm destroy
 186 command return
 187 .Sy EBUSY .
 188 .It Xr zfs-diff 8
 189 Display the difference between a snapshot of a given filesystem and another
 190 snapshot of that filesystem from a later time or the current contents of the
 191 filesystem.
 192 .El
 193 .
 194 .Ss Clones
 195 .Bl -tag -width ""
 196 .It Xr zfs-clone 8
 197 Creates a clone of the given snapshot.
 198 .It Xr zfs-promote 8
 199 Promotes a clone file system to no longer be dependent on its
 200 .Qq origin
 201 snapshot.
 202 .El
 203 .
 204 .Ss Send & Receive
 205 .Bl -tag -width ""
 206 .It Xr zfs-send 8
 207 Generate a send stream, which may be of a filesystem, and may be incremental
 208 from a bookmark.
 209 .It Xr zfs-receive 8
 210 Creates a snapshot whose contents are as specified in the stream provided on
 211 standard input.
 212 If a full stream is received, then a new file system is created as well.
 213 Streams are created using the
 214 .Xr zfs-send 8
 215 subcommand, which by default creates a full stream.
 216 .It Xr zfs-bookmark 8
 217 Creates a new bookmark of the given snapshot or bookmark.
 218 Bookmarks mark the point in time when the snapshot was created, and can be used
 219 as the incremental source for a
 220 .Nm zfs Cm send
 221 command.
 222 .It Xr zfs-redact 8
 223 Generate a new redaction bookmark.
 224 This feature can be used to allow clones of a filesystem to be made available on
 225 a remote system, in the case where their parent need not (or needs to not) be
 226 usable.
 227 .El
 228 .
 229 .Ss Properties
 230 .Bl -tag -width ""
 231 .It Xr zfs-get 8
 232 Displays properties for the given datasets.
 233 .It Xr zfs-set 8
 234 Sets the property or list of properties to the given value(s) for each dataset.
 235 .It Xr zfs-inherit 8
 236 Clears the specified property, causing it to be inherited from an ancestor,
 237 restored to default if no ancestor has the property set, or with the
 238 .Fl S
 239 option reverted to the received value if one exists.
 240 .El
 241 .
 242 .Ss Quotas
 243 .Bl -tag -width ""
 244 .It Xr zfs-userspace 8 Ns / Ns Xr zfs-groupspace 8 Ns / Ns Xr zfs-projectspace 8
 245 Displays space consumed by, and quotas on, each user, group, or project
 246 in the specified filesystem or snapshot.
 247 .It Xr zfs-project 8
 248 List, set, or clear project ID and/or inherit flag on the files or directories.
 249 .El
 250 .
 251 .Ss Mountpoints
 252 .Bl -tag -width ""
 253 .It Xr zfs-mount 8
 254 Displays all ZFS file systems currently mounted, or mount ZFS filesystem
 255 on a path described by its
 256 .Sy mountpoint
 257 property.
 258 .It Xr zfs-unmount 8
 259 Unmounts currently mounted ZFS file systems.
 260 .El
 261 .
 262 .Ss Shares
 263 .Bl -tag -width ""
 264 .It Xr zfs-share 8
 265 Shares available ZFS file systems.
 266 .It Xr zfs-unshare 8
 267 Unshares currently shared ZFS file systems.
 268 .El
 269 .
 270 .Ss Delegated Administration
 271 .Bl -tag -width ""
 272 .It Xr zfs-allow 8
 273 Delegate permissions on the specified filesystem or volume.
 274 .It Xr zfs-unallow 8
 275 Remove delegated permissions on the specified filesystem or volume.
 276 .El
 277 .
 278 .Ss Encryption
 279 .Bl -tag -width ""
 280 .It Xr zfs-change-key 8
 281 Add or change an encryption key on the specified dataset.
 282 .It Xr zfs-load-key 8
 283 Load the key for the specified encrypted dataset, enabling access.
 284 .It Xr zfs-unload-key 8
 285 Unload a key for the specified dataset,
 286 removing the ability to access the dataset.
 287 .El
 288 .
 289 .Ss Channel Programs
 290 .Bl -tag -width ""
 291 .It Xr zfs-program 8
 292 Execute ZFS administrative operations
 293 programmatically via a Lua script-language channel program.
 294 .El
 295 .
 296 .Ss Jails
 297 .Bl -tag -width ""
 298 .It Xr zfs-jail 8
 299 Attaches a filesystem to a jail.
 300 .It Xr zfs-unjail 8
 301 Detaches a filesystem from a jail.
 302 .El
 303 .
 304 .Ss Waiting
 305 .Bl -tag -width ""
 306 .It Xr zfs-wait 8
 307 Wait for background activity in a filesystem to complete.
 308 .El
 309 .
 310 .Sh EXIT STATUS
 311 The
 312 .Nm
 313 utility exits
 314 .Sy 0
 315 on success,
 316 .Sy 1
 317 if an error occurs, and
 318 .Sy 2
 319 if invalid command line options were specified.
 320 .
 321 .Sh EXAMPLES
 322 .\" Examples 1, 4, 6, 7, 11, 14, 16 are shared with zfs-set.8.
 323 .\" Examples 1, 10 are shared with zfs-create.8.
 324 .\" Examples 2, 3, 10, 15 are also shared with zfs-snapshot.8.
 325 .\" Examples 3, 10, 15 are shared with zfs-destroy.8.
 326 .\" Examples 5 are shared with zfs-list.8.
 327 .\" Examples 8 are shared with zfs-rollback.8.
 328 .\" Examples 9, 10 are shared with zfs-clone.8.
 329 .\" Examples 10 are also shared with zfs-promote.8.
 330 .\" Examples 10, 15 also are shared with zfs-rename.8.
 331 .\" Examples 12, 13 are shared with zfs-send.8.
 332 .\" Examples 12, 13 are also shared with zfs-receive.8.
 333 .\" Examples 17, 18, 19, 20, 21 are shared with zfs-allow.8.
 334 .\" Examples 22 are shared with zfs-diff.8.
 335 .\" Examples 23 are shared with zfs-bookmark.8.
 336 .\" Make sure to update them omnidirectionally
 337 .Ss Example 1 : No Creating a ZFS File System Hierarchy
 338 The following commands create a file system named
 339 .Ar pool/home
 340 and a file system named
 341 .Ar pool/home/bob .
 342 The mount point
 343 .Pa /export/home
 344 is set for the parent file system, and is automatically inherited by the child
 345 file system.
 346 .Dl # Nm zfs Cm create Ar pool/home
 347 .Dl # Nm zfs Cm set Sy mountpoint Ns = Ns Ar /export/home pool/home
 348 .Dl # Nm zfs Cm create Ar pool/home/bob
 349 .
 350 .Ss Example 2 : No Creating a ZFS Snapshot
 351 The following command creates a snapshot named
 352 .Ar yesterday .
 353 This snapshot is mounted on demand in the
 354 .Pa .zfs/snapshot
 355 directory at the root of the
 356 .Ar pool/home/bob
 357 file system.
 358 .Dl # Nm zfs Cm snapshot Ar pool/home/bob Ns @ Ns Ar yesterday
 359 .
 360 .Ss Example 3 : No Creating and Destroying Multiple Snapshots
 361 The following command creates snapshots named
 362 .Ar yesterday No of Ar pool/home
 363 and all of its descendent file systems.
 364 Each snapshot is mounted on demand in the
 365 .Pa .zfs/snapshot
 366 directory at the root of its file system.
 367 The second command destroys the newly created snapshots.
 368 .Dl # Nm zfs Cm snapshot Fl r Ar pool/home Ns @ Ns Ar yesterday
 369 .Dl # Nm zfs Cm destroy Fl r Ar pool/home Ns @ Ns Ar yesterday
 370 .
 371 .Ss Example 4 : No Disabling and Enabling File System Compression
 372 The following command disables the
 373 .Sy compression
 374 property for all file systems under
 375 .Ar pool/home .
 376 The next command explicitly enables
 377 .Sy compression
 378 for
 379 .Ar pool/home/anne .
 380 .Dl # Nm zfs Cm set Sy compression Ns = Ns Sy off Ar pool/home
 381 .Dl # Nm zfs Cm set Sy compression Ns = Ns Sy on Ar pool/home/anne
 382 .
 383 .Ss Example 5 : No Listing ZFS Datasets
 384 The following command lists all active file systems and volumes in the system.
 385 Snapshots are displayed if
 386 .Sy listsnaps Ns = Ns Sy on .
 387 The default is
 388 .Sy off .
 389 See
 390 .Xr zpoolprops 7
 391 for more information on pool properties.
 392 .Bd -literal -compact -offset Ds
 393 .No # Nm zfs Cm list
 394 NAME                      USED  AVAIL  REFER  MOUNTPOINT
 395 pool                      450K   457G    18K  /pool
 396 pool/home                 315K   457G    21K  /export/home
 397 pool/home/anne             18K   457G    18K  /export/home/anne
 398 pool/home/bob             276K   457G   276K  /export/home/bob
 399 .Ed
 400 .
 401 .Ss Example 6 : No Setting a Quota on a ZFS File System
 402 The following command sets a quota of 50 Gbytes for
 403 .Ar pool/home/bob :
 404 .Dl # Nm zfs Cm set Sy quota Ns = Ns Ar 50G pool/home/bob
 405 .
 406 .Ss Example 7 : No Listing ZFS Properties
 407 The following command lists all properties for
 408 .Ar pool/home/bob :
 409 .Bd -literal -compact -offset Ds
 410 .No # Nm zfs Cm get Sy all Ar pool/home/bob
 411 NAME           PROPERTY              VALUE                  SOURCE
 412 pool/home/bob  type                  filesystem             -
 413 pool/home/bob  creation              Tue Jul 21 15:53 2009  -
 414 pool/home/bob  used                  21K                    -
 415 pool/home/bob  available             20.0G                  -
 416 pool/home/bob  referenced            21K                    -
 417 pool/home/bob  compressratio         1.00x                  -
 418 pool/home/bob  mounted               yes                    -
 419 pool/home/bob  quota                 20G                    local
 420 pool/home/bob  reservation           none                   default
 421 pool/home/bob  recordsize            128K                   default
 422 pool/home/bob  mountpoint            /pool/home/bob         default
 423 pool/home/bob  sharenfs              off                    default
 424 pool/home/bob  checksum              on                     default
 425 pool/home/bob  compression           on                     local
 426 pool/home/bob  atime                 on                     default
 427 pool/home/bob  devices               on                     default
 428 pool/home/bob  exec                  on                     default
 429 pool/home/bob  setuid                on                     default
 430 pool/home/bob  readonly              off                    default
 431 pool/home/bob  zoned                 off                    default
 432 pool/home/bob  snapdir               hidden                 default
 433 pool/home/bob  acltype               off                    default
 434 pool/home/bob  aclmode               discard                default
 435 pool/home/bob  aclinherit            restricted             default
 436 pool/home/bob  canmount              on                     default
 437 pool/home/bob  xattr                 on                     default
 438 pool/home/bob  copies                1                      default
 439 pool/home/bob  version               4                      -
 440 pool/home/bob  utf8only              off                    -
 441 pool/home/bob  normalization         none                   -
 442 pool/home/bob  casesensitivity       sensitive              -
 443 pool/home/bob  vscan                 off                    default
 444 pool/home/bob  nbmand                off                    default
 445 pool/home/bob  sharesmb              off                    default
 446 pool/home/bob  refquota              none                   default
 447 pool/home/bob  refreservation        none                   default
 448 pool/home/bob  primarycache          all                    default
 449 pool/home/bob  secondarycache        all                    default
 450 pool/home/bob  usedbysnapshots       0                      -
 451 pool/home/bob  usedbydataset         21K                    -
 452 pool/home/bob  usedbychildren        0                      -
 453 pool/home/bob  usedbyrefreservation  0                      -
 454 .Ed
 455 .Pp
 456 The following command gets a single property value:
 457 .Bd -literal -compact -offset Ds
 458 .No # Nm zfs Cm get Fl H o Sy value compression Ar pool/home/bob
 459 on
 460 .Ed
 461 .Pp
 462 The following command lists all properties with local settings for
 463 .Ar pool/home/bob :
 464 .Bd -literal -compact -offset Ds
 465 .No # Nm zfs Cm get Fl r s Sy local Fl o Sy name , Ns Sy property , Ns Sy value all Ar pool/home/bob
 466 NAME           PROPERTY              VALUE
 467 pool/home/bob  quota                 20G
 468 pool/home/bob  compression           on
 469 .Ed
 470 .
 471 .Ss Example 8 : No Rolling Back a ZFS File System
 472 The following command reverts the contents of
 473 .Ar pool/home/anne
 474 to the snapshot named
 475 .Ar yesterday ,
 476 deleting all intermediate snapshots:
 477 .Dl # Nm zfs Cm rollback Fl r Ar pool/home/anne Ns @ Ns Ar yesterday
 478 .
 479 .Ss Example 9 : No Creating a ZFS Clone
 480 The following command creates a writable file system whose initial contents are
 481 the same as
 482 .Ar pool/home/bob@yesterday .
 483 .Dl # Nm zfs Cm clone Ar pool/home/bob@yesterday pool/clone
 484 .
 485 .Ss Example 10 : No Promoting a ZFS Clone
 486 The following commands illustrate how to test out changes to a file system, and
 487 then replace the original file system with the changed one, using clones, clone
 488 promotion, and renaming:
 489 .Bd -literal -compact -offset Ds
 490 .No # Nm zfs Cm create Ar pool/project/production
 491   populate /pool/project/production with data
 492 .No # Nm zfs Cm snapshot Ar pool/project/production Ns @ Ns Ar today
 493 .No # Nm zfs Cm clone Ar pool/project/production@today pool/project/beta
 494   make changes to /pool/project/beta and test them
 495 .No # Nm zfs Cm promote Ar pool/project/beta
 496 .No # Nm zfs Cm rename Ar pool/project/production pool/project/legacy
 497 .No # Nm zfs Cm rename Ar pool/project/beta pool/project/production
 498   once the legacy version is no longer needed, it can be destroyed
 499 .No # Nm zfs Cm destroy Ar pool/project/legacy
 500 .Ed
 501 .
 502 .Ss Example 11 : No Inheriting ZFS Properties
 503 The following command causes
 504 .Ar pool/home/bob No and Ar pool/home/anne
 505 to inherit the
 506 .Sy checksum
 507 property from their parent.
 508 .Dl # Nm zfs Cm inherit Sy checksum Ar pool/home/bob pool/home/anne
 509 .
 510 .Ss Example 12 : No Remotely Replicating ZFS Data
 511 The following commands send a full stream and then an incremental stream to a
 512 remote machine, restoring them into
 513 .Em poolB/received/fs@a
 514 and
 515 .Em poolB/received/fs@b ,
 516 respectively.
 517 .Em poolB
 518 must contain the file system
 519 .Em poolB/received ,
 520 and must not initially contain
 521 .Em poolB/received/fs .
 522 .Bd -literal -compact -offset Ds
 523 .No # Nm zfs Cm send Ar pool/fs@a |
 524 .No "   " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs Ns @ Ns Ar a
 525 .No # Nm zfs Cm send Fl i Ar a pool/fs@b |
 526 .No "   " Nm ssh Ar host Nm zfs Cm receive Ar poolB/received/fs
 527 .Ed
 528 .
 529 .Ss Example 13 : No Using the Nm zfs Cm receive Fl d No Option
 530 The following command sends a full stream of
 531 .Ar poolA/fsA/fsB@snap
 532 to a remote machine, receiving it into
 533 .Ar poolB/received/fsA/fsB@snap .
 534 The
 535 .Ar fsA/fsB@snap
 536 portion of the received snapshot's name is determined from the name of the sent
 537 snapshot.
 538 .Ar poolB
 539 must contain the file system
 540 .Ar poolB/received .
 541 If
 542 .Ar poolB/received/fsA
 543 does not exist, it is created as an empty file system.
 544 .Bd -literal -compact -offset Ds
 545 .No # Nm zfs Cm send Ar poolA/fsA/fsB@snap |
 546 .No "   " Nm ssh Ar host Nm zfs Cm receive Fl d Ar poolB/received
 547 .Ed
 548 .
 549 .Ss Example 14 : No Setting User Properties
 550 The following example sets the user-defined
 551 .Ar com.example : Ns Ar department
 552 property for a dataset:
 553 .Dl # Nm zfs Cm set Ar com.example : Ns Ar department Ns = Ns Ar 12345 tank/accounting
 554 .
 555 .Ss Example 15 : No Performing a Rolling Snapshot
 556 The following example shows how to maintain a history of snapshots with a
 557 consistent naming scheme.
 558 To keep a week's worth of snapshots, the user destroys the oldest snapshot,
 559 renames the remaining snapshots, and then creates a new snapshot, as follows:
 560 .Bd -literal -compact -offset Ds
 561 .No # Nm zfs Cm destroy Fl r Ar pool/users@7daysago
 562 .No # Nm zfs Cm rename Fl r Ar pool/users@6daysago No @ Ns Ar 7daysago
 563 .No # Nm zfs Cm rename Fl r Ar pool/users@5daysago No @ Ns Ar 6daysago
 564 .No # Nm zfs Cm rename Fl r Ar pool/users@4daysago No @ Ns Ar 5daysago
 565 .No # Nm zfs Cm rename Fl r Ar pool/users@3daysago No @ Ns Ar 4daysago
 566 .No # Nm zfs Cm rename Fl r Ar pool/users@2daysago No @ Ns Ar 3daysago
 567 .No # Nm zfs Cm rename Fl r Ar pool/users@yesterday No @ Ns Ar 2daysago
 568 .No # Nm zfs Cm rename Fl r Ar pool/users@today No @ Ns Ar yesterday
 569 .No # Nm zfs Cm snapshot Fl r Ar pool/users Ns @ Ns Ar today
 570 .Ed
 571 .
 572 .Ss Example 16 : No Setting sharenfs Property Options on a ZFS File System
 573 The following commands show how to set
 574 .Sy sharenfs
 575 property options to enable read-write
 576 access for a set of IP addresses and to enable root access for system
 577 .Qq neo
 578 on the
 579 .Ar tank/home
 580 file system:
 581 .Dl # Nm zfs Cm set Sy sharenfs Ns = Ns ' Ns Ar rw Ns =@123.123.0.0/16:[::1],root= Ns Ar neo Ns ' tank/home
 582 .Pp
 583 If you are using DNS for host name resolution,
 584 specify the fully-qualified hostname.
 585 .
 586 .Ss Example 17 : No Delegating ZFS Administration Permissions on a ZFS Dataset
 587 The following example shows how to set permissions so that user
 588 .Ar cindys
 589 can create, destroy, mount, and take snapshots on
 590 .Ar tank/cindys .
 591 The permissions on
 592 .Ar tank/cindys
 593 are also displayed.
 594 .Bd -literal -compact -offset Ds
 595 .No # Nm zfs Cm allow Sy cindys create , Ns Sy destroy , Ns Sy mount , Ns Sy snapshot Ar tank/cindys
 596 .No # Nm zfs Cm allow Ar tank/cindys
 597 ---- Permissions on tank/cindys --------------------------------------
 598 Local+Descendent permissions:
 599         user cindys create,destroy,mount,snapshot
 600 .Ed
 601 .Pp
 602 Because the
 603 .Ar tank/cindys
 604 mount point permission is set to 755 by default, user
 605 .Ar cindys
 606 will be unable to mount file systems under
 607 .Ar tank/cindys .
 608 Add an ACE similar to the following syntax to provide mount point access:
 609 .Dl # Cm chmod No A+user : Ns Ar cindys Ns :add_subdirectory:allow Ar /tank/cindys
 610 .
 611 .Ss Example 18 : No Delegating Create Time Permissions on a ZFS Dataset
 612 The following example shows how to grant anyone in the group
 613 .Ar staff
 614 to create file systems in
 615 .Ar tank/users .
 616 This syntax also allows staff members to destroy their own file systems, but not
 617 destroy anyone else's file system.
 618 The permissions on
 619 .Ar tank/users
 620 are also displayed.
 621 .Bd -literal -compact -offset Ds
 622 .No # Nm zfs Cm allow Ar staff Sy create , Ns Sy mount Ar tank/users
 623 .No # Nm zfs Cm allow Fl c Sy destroy Ar tank/users
 624 .No # Nm zfs Cm allow Ar tank/users
 625 ---- Permissions on tank/users ---------------------------------------
 626 Permission sets:
 627         destroy
 628 Local+Descendent permissions:
 629         group staff create,mount
 630 .Ed
 631 .
 632 .Ss Example 19 : No Defining and Granting a Permission Set on a ZFS Dataset
 633 The following example shows how to define and grant a permission set on the
 634 .Ar tank/users
 635 file system.
 636 The permissions on
 637 .Ar tank/users
 638 are also displayed.
 639 .Bd -literal -compact -offset Ds
 640 .No # Nm zfs Cm allow Fl s No @ Ns Ar pset Sy create , Ns Sy destroy , Ns Sy snapshot , Ns Sy mount Ar tank/users
 641 .No # Nm zfs Cm allow staff No @ Ns Ar pset tank/users
 642 .No # Nm zfs Cm allow Ar tank/users
 643 ---- Permissions on tank/users ---------------------------------------
 644 Permission sets:
 645         @pset create,destroy,mount,snapshot
 646 Local+Descendent permissions:
 647         group staff @pset
 648 .Ed
 649 .
 650 .Ss Example 20 : No Delegating Property Permissions on a ZFS Dataset
 651 The following example shows to grant the ability to set quotas and reservations
 652 on the
 653 .Ar users/home
 654 file system.
 655 The permissions on
 656 .Ar users/home
 657 are also displayed.
 658 .Bd -literal -compact -offset Ds
 659 .No # Nm zfs Cm allow Ar cindys Sy quota , Ns Sy reservation Ar users/home
 660 .No # Nm zfs Cm allow Ar users/home
 661 ---- Permissions on users/home ---------------------------------------
 662 Local+Descendent permissions:
 663         user cindys quota,reservation
 664 cindys% zfs set quota=10G users/home/marks
 665 cindys% zfs get quota users/home/marks
 666 NAME              PROPERTY  VALUE  SOURCE
 667 users/home/marks  quota     10G    local
 668 .Ed
 669 .
 670 .Ss Example 21 : No Removing ZFS Delegated Permissions on a ZFS Dataset
 671 The following example shows how to remove the snapshot permission from the
 672 .Ar staff
 673 group on the
 674 .Sy tank/users
 675 file system.
 676 The permissions on
 677 .Sy tank/users
 678 are also displayed.
 679 .Bd -literal -compact -offset Ds
 680 .No # Nm zfs Cm unallow Ar staff Sy snapshot Ar tank/users
 681 .No # Nm zfs Cm allow Ar tank/users
 682 ---- Permissions on tank/users ---------------------------------------
 683 Permission sets:
 684         @pset create,destroy,mount,snapshot
 685 Local+Descendent permissions:
 686         group staff @pset
 687 .Ed
 688 .
 689 .Ss Example 22 : No Showing the differences between a snapshot and a ZFS Dataset
 690 The following example shows how to see what has changed between a prior
 691 snapshot of a ZFS dataset and its current state.
 692 The
 693 .Fl F
 694 option is used to indicate type information for the files affected.
 695 .Bd -literal -compact -offset Ds
 696 .No # Nm zfs Cm diff Fl F Ar tank/test@before tank/test
 697 M       /       /tank/test/
 698 M       F       /tank/test/linked      (+1)
 699 R       F       /tank/test/oldname -> /tank/test/newname
 700 -       F       /tank/test/deleted
 701 +       F       /tank/test/created
 702 M       F       /tank/test/modified
 703 .Ed
 704 .
 705 .Ss Example 23 : No Creating a bookmark
 706 The following example creates a bookmark to a snapshot.
 707 This bookmark can then be used instead of a snapshot in send streams.
 708 .Dl # Nm zfs Cm bookmark Ar rpool Ns @ Ns Ar snapshot rpool Ns # Ns Ar bookmark
 709 .
 710 .Ss Example 24 : No Setting Sy sharesmb No Property Options on a ZFS File System
 711 The following example show how to share SMB filesystem through ZFS.
 712 Note that a user and their password must be given.
 713 .Dl # Nm smbmount Ar //127.0.0.1/share_tmp /mnt/tmp Fl o No user=workgroup/turbo,password=obrut,uid=1000
 714 .Pp
 715 Minimal
 716 .Pa /etc/samba/smb.conf
 717 configuration is required, as follows.
 718 .Pp
 719 Samba will need to bind to the loopback interface for the ZFS utilities to
 720 communicate with Samba.
 721 This is the default behavior for most Linux distributions.
 722 .Pp
 723 Samba must be able to authenticate a user.
 724 This can be done in a number of ways
 725 .Pq Xr passwd 5 , LDAP , Xr smbpasswd 5 , &c.\& .
 726 How to do this is outside the scope of this document – refer to
 727 .Xr smb.conf 5
 728 for more information.
 729 .Pp
 730 See the
 731 .Sx USERSHARES
 732 section for all configuration options,
 733 in case you need to modify any options of the share afterwards.
 734 Do note that any changes done with the
 735 .Xr net 8
 736 command will be undone if the share is ever unshared (like via a reboot).
 737 .
 738 .Sh ENVIRONMENT VARIABLES
 739 .Bl -tag -width "ZFS_MODULE_TIMEOUT"
 740 .It Sy ZFS_COLOR
 741 Use ANSI color in
 742 .Nm zfs Cm diff
 743 and
 744 .Nm zfs Cm list
 745 output.
 746 .It Sy ZFS_MOUNT_HELPER
 747 Cause
 748 .Nm zfs Cm mount
 749 to use
 750 .Xr mount 8
 751 to mount ZFS datasets.
 752 This option is provided for backwards compatibility with older ZFS versions.
 753 .
 754 .It Sy ZFS_SET_PIPE_MAX
 755 Tells
 756 .Nm zfs
 757 to set the maximum pipe size for sends/recieves.
 758 Disabled by default on Linux
 759 due to an unfixed deadlock in Linux's pipe size handling code.
 760 .
 761 .\" Shared with zpool.8
 762 .It Sy ZFS_MODULE_TIMEOUT
 763 Time, in seconds, to wait for
 764 .Pa /dev/zfs
 765 to appear.
 766 Defaults to
 767 .Sy 10 ,
 768 max
 769 .Sy 600 Pq 10 minutes .
 770 If
 771 .Pf < Sy 0 ,
 772 wait forever; if
 773 .Sy 0 ,
 774 don't wait.
 775 .El
 776 .
 777 .Sh INTERFACE STABILITY
 778 .Sy Committed .
 779 .
 780 .Sh SEE ALSO
 781 .Xr attr 1 ,
 782 .Xr gzip 1 ,
 783 .Xr ssh 1 ,
 784 .Xr chmod 2 ,
 785 .Xr fsync 2 ,
 786 .Xr stat 2 ,
 787 .Xr write 2 ,
 788 .Xr acl 5 ,
 789 .Xr attributes 5 ,
 790 .Xr exports 5 ,
 791 .Xr zfsconcepts 7 ,
 792 .Xr zfsprops 7 ,
 793 .Xr exportfs 8 ,
 794 .Xr mount 8 ,
 795 .Xr net 8 ,
 796 .Xr selinux 8 ,
 797 .Xr zfs-allow 8 ,
 798 .Xr zfs-bookmark 8 ,
 799 .Xr zfs-change-key 8 ,
 800 .Xr zfs-clone 8 ,
 801 .Xr zfs-create 8 ,
 802 .Xr zfs-destroy 8 ,
 803 .Xr zfs-diff 8 ,
 804 .Xr zfs-get 8 ,
 805 .Xr zfs-groupspace 8 ,
 806 .Xr zfs-hold 8 ,
 807 .Xr zfs-inherit 8 ,
 808 .Xr zfs-jail 8 ,
 809 .Xr zfs-list 8 ,
 810 .Xr zfs-load-key 8 ,
 811 .Xr zfs-mount 8 ,
 812 .Xr zfs-program 8 ,
 813 .Xr zfs-project 8 ,
 814 .Xr zfs-projectspace 8 ,
 815 .Xr zfs-promote 8 ,
 816 .Xr zfs-receive 8 ,
 817 .Xr zfs-redact 8 ,
 818 .Xr zfs-release 8 ,
 819 .Xr zfs-rename 8 ,
 820 .Xr zfs-rollback 8 ,
 821 .Xr zfs-send 8 ,
 822 .Xr zfs-set 8 ,
 823 .Xr zfs-share 8 ,
 824 .Xr zfs-snapshot 8 ,
 825 .Xr zfs-unallow 8 ,
 826 .Xr zfs-unjail 8 ,
 827 .Xr zfs-unload-key 8 ,
 828 .Xr zfs-unmount 8 ,
 829 .Xr zfs-unshare 8 ,
 830 .Xr zfs-upgrade 8 ,
 831 .Xr zfs-userspace 8 ,
 832 .Xr zfs-wait 8 ,
 833 .Xr zpool 8