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