| blob | dd578cb74aac2b40b999669791489957126d0906 |
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