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