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