]>
Commit | Line | Data |
---|---|---|
5990da81 YP |
1 | .\" |
2 | .\" CDDL HEADER START | |
3 | .\" | |
4 | .\" The contents of this file are subject to the terms of the | |
5 | .\" Common Development and Distribution License (the "License"). | |
6 | .\" You may not use this file except in compliance with the License. | |
7 | .\" | |
8 | .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE | |
9 | .\" or http://www.opensolaris.org/os/licensing. | |
10 | .\" See the License for the specific language governing permissions | |
11 | .\" and limitations under the License. | |
12 | .\" | |
13 | .\" When distributing Covered Code, include this CDDL HEADER in each | |
14 | .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. | |
15 | .\" If applicable, add the following below this CDDL HEADER, with the | |
16 | .\" fields enclosed by brackets "[]" replaced with your own identifying | |
17 | .\" information: Portions Copyright [yyyy] [name of copyright owner] | |
18 | .\" | |
19 | .\" CDDL HEADER END | |
20 | .\" | |
21 | .\" | |
058ac9ba | 22 | .\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved. |
5990da81 | 23 | .\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org> |
c568ab8d | 24 | .\" Copyright (c) 2011, 2019 by Delphix. All rights reserved. |
9759c60f | 25 | .\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved. |
44f09cdc BB |
26 | .\" Copyright (c) 2014, Joyent, Inc. All rights reserved. |
27 | .\" Copyright (c) 2014 by Adam Stevko. All rights reserved. | |
28 | .\" Copyright (c) 2014 Integros [integros.com] | |
9810410a | 29 | .\" Copyright 2019 Richard Laager. All rights reserved. |
cb110f25 | 30 | .\" Copyright 2018 Nexenta Systems, Inc. |
d22f3a82 | 31 | .\" Copyright 2018 Joyent, Inc. |
5990da81 | 32 | .\" |
22448f08 | 33 | .Dd Jan 05, 2019 |
44f09cdc BB |
34 | .Dt ZFS 8 SMM |
35 | .Os Linux | |
36 | .Sh NAME | |
37 | .Nm zfs | |
38 | .Nd configures ZFS file systems | |
39 | .Sh SYNOPSIS | |
40 | .Nm | |
50478c6d | 41 | .Fl ?V |
44f09cdc BB |
42 | .Nm |
43 | .Cm create | |
44 | .Op Fl p | |
45 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... | |
46 | .Ar filesystem | |
47 | .Nm | |
48 | .Cm create | |
49 | .Op Fl ps | |
50 | .Op Fl b Ar blocksize | |
51 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... | |
52 | .Fl V Ar size Ar volume | |
53 | .Nm | |
54 | .Cm destroy | |
55 | .Op Fl Rfnprv | |
56 | .Ar filesystem Ns | Ns Ar volume | |
57 | .Nm | |
58 | .Cm destroy | |
59 | .Op Fl Rdnprv | |
60 | .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns | |
61 | .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... | |
62 | .Nm | |
63 | .Cm destroy | |
64 | .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark | |
65 | .Nm | |
66 | .Cm snapshot | |
67 | .Op Fl r | |
90cdf283 | 68 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
44f09cdc BB |
69 | .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... |
70 | .Nm | |
71 | .Cm rollback | |
72 | .Op Fl Rfr | |
73 | .Ar snapshot | |
74 | .Nm | |
75 | .Cm clone | |
76 | .Op Fl p | |
77 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... | |
78 | .Ar snapshot Ar filesystem Ns | Ns Ar volume | |
79 | .Nm | |
80 | .Cm promote | |
81 | .Ar clone-filesystem | |
82 | .Nm | |
83 | .Cm rename | |
84 | .Op Fl f | |
85 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
86 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
87 | .Nm | |
88 | .Cm rename | |
89 | .Op Fl fp | |
90 | .Ar filesystem Ns | Ns Ar volume | |
91 | .Ar filesystem Ns | Ns Ar volume | |
92 | .Nm | |
93 | .Cm rename | |
94 | .Fl r | |
95 | .Ar snapshot Ar snapshot | |
96 | .Nm | |
97 | .Cm list | |
98 | .Op Fl r Ns | Ns Fl d Ar depth | |
99 | .Op Fl Hp | |
100 | .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc | |
101 | .Oo Fl s Ar property Oc Ns ... | |
102 | .Oo Fl S Ar property Oc Ns ... | |
103 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
104 | .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... | |
105 | .Nm | |
106 | .Cm set | |
107 | .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... | |
108 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... | |
109 | .Nm | |
110 | .Cm get | |
111 | .Op Fl r Ns | Ns Fl d Ar depth | |
112 | .Op Fl Hp | |
113 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
114 | .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc | |
115 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
116 | .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... | |
48b0b649 | 117 | .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... |
44f09cdc BB |
118 | .Nm |
119 | .Cm inherit | |
120 | .Op Fl rS | |
121 | .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... | |
122 | .Nm | |
123 | .Cm upgrade | |
124 | .Nm | |
125 | .Cm upgrade | |
126 | .Fl v | |
127 | .Nm | |
128 | .Cm upgrade | |
129 | .Op Fl r | |
130 | .Op Fl V Ar version | |
131 | .Fl a | Ar filesystem | |
132 | .Nm | |
133 | .Cm userspace | |
134 | .Op Fl Hinp | |
135 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
136 | .Oo Fl s Ar field Oc Ns ... | |
137 | .Oo Fl S Ar field Oc Ns ... | |
138 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
139 | .Ar filesystem Ns | Ns Ar snapshot | |
140 | .Nm | |
141 | .Cm groupspace | |
142 | .Op Fl Hinp | |
143 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
144 | .Oo Fl s Ar field Oc Ns ... | |
145 | .Oo Fl S Ar field Oc Ns ... | |
146 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
147 | .Ar filesystem Ns | Ns Ar snapshot | |
148 | .Nm | |
9c5167d1 NF |
149 | .Cm projectspace |
150 | .Op Fl Hp | |
151 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
152 | .Oo Fl s Ar field Oc Ns ... | |
153 | .Oo Fl S Ar field Oc Ns ... | |
154 | .Ar filesystem Ns | Ns Ar snapshot | |
155 | .Nm | |
156 | .Cm project | |
157 | .Oo Fl d Ns | Ns Fl r Ns Oc | |
158 | .Ar file Ns | Ns Ar directory Ns ... | |
159 | .Nm | |
160 | .Cm project | |
161 | .Fl C | |
162 | .Oo Fl kr Ns Oc | |
163 | .Ar file Ns | Ns Ar directory Ns ... | |
164 | .Nm | |
165 | .Cm project | |
166 | .Fl c | |
167 | .Oo Fl 0 Ns Oc | |
168 | .Oo Fl d Ns | Ns Fl r Ns Oc | |
169 | .Op Fl p Ar id | |
170 | .Ar file Ns | Ns Ar directory Ns ... | |
171 | .Nm | |
172 | .Cm project | |
173 | .Op Fl p Ar id | |
174 | .Oo Fl rs Ns Oc | |
175 | .Ar file Ns | Ns Ar directory Ns ... | |
176 | .Nm | |
44f09cdc BB |
177 | .Cm mount |
178 | .Nm | |
179 | .Cm mount | |
b5256303 | 180 | .Op Fl Olv |
44f09cdc BB |
181 | .Op Fl o Ar options |
182 | .Fl a | Ar filesystem | |
183 | .Nm | |
184 | .Cm unmount | |
185 | .Op Fl f | |
186 | .Fl a | Ar filesystem Ns | Ns Ar mountpoint | |
187 | .Nm | |
188 | .Cm share | |
189 | .Fl a | Ar filesystem | |
190 | .Nm | |
191 | .Cm unshare | |
192 | .Fl a | Ar filesystem Ns | Ns Ar mountpoint | |
193 | .Nm | |
194 | .Cm bookmark | |
195 | .Ar snapshot bookmark | |
196 | .Nm | |
197 | .Cm send | |
9c5e88b1 | 198 | .Op Fl DLPRbcehnpvw |
44f09cdc BB |
199 | .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot |
200 | .Ar snapshot | |
201 | .Nm | |
202 | .Cm send | |
835db585 | 203 | .Op Fl LPcenvw |
44f09cdc BB |
204 | .Op Fl i Ar snapshot Ns | Ns Ar bookmark |
205 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
206 | .Nm | |
207 | .Cm send | |
208 | .Op Fl Penv | |
209 | .Fl t Ar receive_resume_token | |
210 | .Nm | |
211 | .Cm receive | |
9c5e88b1 | 212 | .Op Fl Fhnsuv |
44f09cdc BB |
213 | .Op Fl o Sy origin Ns = Ns Ar snapshot |
214 | .Op Fl o Ar property Ns = Ns Ar value | |
215 | .Op Fl x Ar property | |
216 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
217 | .Nm | |
218 | .Cm receive | |
9c5e88b1 | 219 | .Op Fl Fhnsuv |
44f09cdc BB |
220 | .Op Fl d Ns | Ns Fl e |
221 | .Op Fl o Sy origin Ns = Ns Ar snapshot | |
222 | .Op Fl o Ar property Ns = Ns Ar value | |
223 | .Op Fl x Ar property | |
224 | .Ar filesystem | |
225 | .Nm | |
226 | .Cm receive | |
227 | .Fl A | |
228 | .Ar filesystem Ns | Ns Ar volume | |
229 | .Nm | |
230 | .Cm allow | |
231 | .Ar filesystem Ns | Ns Ar volume | |
232 | .Nm | |
233 | .Cm allow | |
234 | .Op Fl dglu | |
235 | .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... | |
236 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
237 | .Ar setname Oc Ns ... | |
238 | .Ar filesystem Ns | Ns Ar volume | |
239 | .Nm | |
240 | .Cm allow | |
241 | .Op Fl dl | |
242 | .Fl e Ns | Ns Sy everyone | |
243 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
244 | .Ar setname Oc Ns ... | |
245 | .Ar filesystem Ns | Ns Ar volume | |
246 | .Nm | |
247 | .Cm allow | |
248 | .Fl c | |
249 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
250 | .Ar setname Oc Ns ... | |
251 | .Ar filesystem Ns | Ns Ar volume | |
252 | .Nm | |
253 | .Cm allow | |
254 | .Fl s No @ Ns Ar setname | |
255 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
256 | .Ar setname Oc Ns ... | |
257 | .Ar filesystem Ns | Ns Ar volume | |
258 | .Nm | |
259 | .Cm unallow | |
260 | .Op Fl dglru | |
261 | .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... | |
262 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
263 | .Ar setname Oc Ns ... Oc | |
264 | .Ar filesystem Ns | Ns Ar volume | |
265 | .Nm | |
266 | .Cm unallow | |
267 | .Op Fl dlr | |
268 | .Fl e Ns | Ns Sy everyone | |
269 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
270 | .Ar setname Oc Ns ... Oc | |
271 | .Ar filesystem Ns | Ns Ar volume | |
272 | .Nm | |
273 | .Cm unallow | |
274 | .Op Fl r | |
275 | .Fl c | |
276 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
277 | .Ar setname Oc Ns ... Oc | |
278 | .Ar filesystem Ns | Ns Ar volume | |
279 | .Nm | |
280 | .Cm unallow | |
281 | .Op Fl r | |
282 | .Fl s @ Ns Ar setname | |
283 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
284 | .Ar setname Oc Ns ... Oc | |
285 | .Ar filesystem Ns | Ns Ar volume | |
286 | .Nm | |
287 | .Cm hold | |
288 | .Op Fl r | |
289 | .Ar tag Ar snapshot Ns ... | |
290 | .Nm | |
291 | .Cm holds | |
a9d6270a | 292 | .Op Fl rH |
44f09cdc BB |
293 | .Ar snapshot Ns ... |
294 | .Nm | |
295 | .Cm release | |
296 | .Op Fl r | |
297 | .Ar tag Ar snapshot Ns ... | |
298 | .Nm | |
299 | .Cm diff | |
300 | .Op Fl FHt | |
301 | .Ar snapshot Ar snapshot Ns | Ns Ar filesystem | |
b5256303 | 302 | .Nm |
d99a0153 | 303 | .Cm program |
272b5d73 | 304 | .Op Fl jn |
c568ab8d MA |
305 | .Op Fl t Ar instruction-limit |
306 | .Op Fl m Ar memory-limit | |
d99a0153 CW |
307 | .Ar pool script |
308 | .Op Ar arg1 No ... | |
309 | .Nm | |
b5256303 TC |
310 | .Cm load-key |
311 | .Op Fl nr | |
312 | .Op Fl L Ar keylocation | |
313 | .Fl a | Ar filesystem | |
314 | .Nm | |
315 | .Cm unload-key | |
316 | .Op Fl r | |
317 | .Fl a | Ar filesystem | |
318 | .Nm | |
319 | .Cm change-key | |
320 | .Op Fl l | |
321 | .Op Fl o Ar keylocation Ns = Ns Ar value | |
322 | .Op Fl o Ar keyformat Ns = Ns Ar value | |
323 | .Op Fl o Ar pbkdf2iters Ns = Ns Ar value | |
324 | .Ar filesystem | |
325 | .Nm | |
326 | .Cm change-key | |
327 | .Fl i | |
328 | .Op Fl l | |
329 | .Ar filesystem | |
50478c6d T |
330 | .Nm |
331 | .Cm version | |
44f09cdc BB |
332 | .Sh DESCRIPTION |
333 | The | |
334 | .Nm | |
335 | command configures ZFS datasets within a ZFS storage pool, as described in | |
336 | .Xr zpool 8 . | |
337 | A dataset is identified by a unique path within the ZFS namespace. | |
338 | For example: | |
339 | .Bd -literal | |
058ac9ba | 340 | pool/{filesystem,volume,snapshot} |
44f09cdc BB |
341 | .Ed |
342 | .Pp | |
343 | where the maximum length of a dataset name is | |
344 | .Dv MAXNAMELEN | |
a7ed98d8 SD |
345 | .Pq 256 bytes |
346 | and the maximum amount of nesting allowed in a path is 50 levels deep. | |
44f09cdc | 347 | .Pp |
058ac9ba | 348 | A dataset can be one of the following: |
44f09cdc BB |
349 | .Bl -tag -width "file system" |
350 | .It Sy file system | |
351 | A ZFS dataset of type | |
352 | .Sy filesystem | |
353 | can be mounted within the standard system namespace and behaves like other file | |
354 | systems. | |
355 | While ZFS file systems are designed to be POSIX compliant, known issues exist | |
356 | that prevent compliance in some cases. | |
357 | Applications that depend on standards conformance might fail due to non-standard | |
358 | behavior when checking file system free space. | |
359 | .It Sy volume | |
360 | A logical volume exported as a raw or block device. | |
9810410a | 361 | This type of dataset should only be used when a block device is required. |
44f09cdc BB |
362 | File systems are typically used in most environments. |
363 | .It Sy snapshot | |
364 | A read-only version of a file system or volume at a given point in time. | |
365 | It is specified as | |
366 | .Ar filesystem Ns @ Ns Ar name | |
367 | or | |
368 | .Ar volume Ns @ Ns Ar name . | |
369 | .It Sy bookmark | |
370 | Much like a | |
371 | .Sy snapshot , | |
372 | but without the hold on on-disk data. It can be used as the source of a send | |
373 | (but not for a receive). It is specified as | |
374 | .Ar filesystem Ns # Ns Ar name | |
375 | or | |
376 | .Ar volume Ns # Ns Ar name . | |
377 | .El | |
378 | .Ss ZFS File System Hierarchy | |
379 | A ZFS storage pool is a logical collection of devices that provide space for | |
380 | datasets. | |
381 | A storage pool is also the root of the ZFS file system hierarchy. | |
382 | .Pp | |
383 | The root of the pool can be accessed as a file system, such as mounting and | |
384 | unmounting, taking snapshots, and setting properties. | |
385 | The physical storage characteristics, however, are managed by the | |
386 | .Xr zpool 8 | |
387 | command. | |
388 | .Pp | |
389 | See | |
390 | .Xr zpool 8 | |
391 | for more information on creating and administering pools. | |
392 | .Ss Snapshots | |
393 | A snapshot is a read-only copy of a file system or volume. | |
394 | Snapshots can be created extremely quickly, and initially consume no additional | |
395 | space within the pool. | |
396 | As data within the active dataset changes, the snapshot consumes more data than | |
397 | would otherwise be shared with the active dataset. | |
398 | .Pp | |
399 | Snapshots can have arbitrary names. | |
400 | Snapshots of volumes can be cloned or rolled back, visibility is determined | |
401 | by the | |
402 | .Sy snapdev | |
403 | property of the parent volume. | |
404 | .Pp | |
405 | File system snapshots can be accessed under the | |
406 | .Pa .zfs/snapshot | |
407 | directory in the root of the file system. | |
408 | Snapshots are automatically mounted on demand and may be unmounted at regular | |
409 | intervals. | |
410 | The visibility of the | |
411 | .Pa .zfs | |
412 | directory can be controlled by the | |
413 | .Sy snapdir | |
414 | property. | |
415 | .Ss Bookmarks | |
416 | A bookmark is like a snapshot, a read-only copy of a file system or volume. | |
417 | Bookmarks can be created extremely quickly, compared to snapshots, and they | |
418 | consume no additional space within the pool. Bookmarks can also have arbitrary | |
419 | names, much like snapshots. | |
420 | .Pp | |
421 | Unlike snapshots, bookmarks can not be accessed through the filesystem in any | |
422 | way. From a storage standpoint a bookmark just provides a way to reference | |
423 | when a snapshot was created as a distinct object. Bookmarks are initially | |
424 | tied to a snapshot, not the filesystem or volume, and they will survive if the | |
425 | snapshot itself is destroyed. Since they are very light weight there's little | |
426 | incentive to destroy them. | |
427 | .Ss Clones | |
428 | A clone is a writable volume or file system whose initial contents are the same | |
429 | as another dataset. | |
430 | As with snapshots, creating a clone is nearly instantaneous, and initially | |
431 | consumes no additional space. | |
432 | .Pp | |
433 | Clones can only be created from a snapshot. | |
434 | When a snapshot is cloned, it creates an implicit dependency between the parent | |
435 | and child. | |
436 | Even though the clone is created somewhere else in the dataset hierarchy, the | |
437 | original snapshot cannot be destroyed as long as a clone exists. | |
438 | The | |
439 | .Sy origin | |
440 | property exposes this dependency, and the | |
441 | .Cm destroy | |
442 | command lists any such dependencies, if they exist. | |
443 | .Pp | |
444 | The clone parent-child dependency relationship can be reversed by using the | |
445 | .Cm promote | |
446 | subcommand. | |
447 | This causes the | |
448 | .Qq origin | |
449 | file system to become a clone of the specified file system, which makes it | |
450 | possible to destroy the file system that the clone was created from. | |
451 | .Ss "Mount Points" | |
452 | Creating a ZFS file system is a simple operation, so the number of file systems | |
453 | per system is likely to be numerous. | |
454 | To cope with this, ZFS automatically manages mounting and unmounting file | |
455 | systems without the need to edit the | |
456 | .Pa /etc/fstab | |
457 | file. | |
458 | All automatically managed file systems are mounted by ZFS at boot time. | |
459 | .Pp | |
460 | By default, file systems are mounted under | |
461 | .Pa /path , | |
462 | where | |
463 | .Ar path | |
464 | is the name of the file system in the ZFS namespace. | |
465 | Directories are created and destroyed as needed. | |
466 | .Pp | |
467 | A file system can also have a mount point set in the | |
468 | .Sy mountpoint | |
469 | property. | |
470 | This directory is created as needed, and ZFS automatically mounts the file | |
471 | system when the | |
472 | .Nm zfs Cm mount Fl a | |
473 | command is invoked | |
474 | .Po without editing | |
475 | .Pa /etc/fstab | |
476 | .Pc . | |
477 | The | |
478 | .Sy mountpoint | |
479 | property can be inherited, so if | |
480 | .Em pool/home | |
481 | has a mount point of | |
482 | .Pa /export/stuff , | |
483 | then | |
484 | .Em pool/home/user | |
485 | automatically inherits a mount point of | |
486 | .Pa /export/stuff/user . | |
487 | .Pp | |
488 | A file system | |
489 | .Sy mountpoint | |
490 | property of | |
491 | .Sy none | |
492 | prevents the file system from being mounted. | |
493 | .Pp | |
494 | If needed, ZFS file systems can also be managed with traditional tools | |
495 | .Po | |
496 | .Nm mount , | |
497 | .Nm umount , | |
498 | .Pa /etc/fstab | |
499 | .Pc . | |
500 | If a file system's mount point is set to | |
501 | .Sy legacy , | |
502 | ZFS makes no attempt to manage the file system, and the administrator is | |
5c2552c5 AR |
503 | responsible for mounting and unmounting the file system. Because pools must |
504 | be imported before a legacy mount can succeed, administrators should ensure | |
505 | that legacy mounts are only attempted after the zpool import process | |
506 | finishes at boot time. For example, on machines using systemd, the mount | |
507 | option | |
508 | .Pp | |
509 | .Nm x-systemd.requires=zfs-import.target | |
510 | .Pp | |
511 | will ensure that the zfs-import completes before systemd attempts mounting | |
512 | the filesystem. See systemd.mount(5) for details. | |
44f09cdc BB |
513 | .Ss Deduplication |
514 | Deduplication is the process for removing redundant data at the block level, | |
515 | reducing the total amount of data stored. If a file system has the | |
516 | .Sy dedup | |
517 | property enabled, duplicate data blocks are removed synchronously. The result | |
518 | is that only unique data is stored and common components are shared among files. | |
519 | .Pp | |
520 | Deduplicating data is a very resource-intensive operation. It is generally | |
521 | recommended that you have at least 1.25 GiB of RAM per 1 TiB of storage when | |
522 | you enable deduplication. Calculating the exact requirement depends heavily | |
523 | on the type of data stored in the pool. | |
524 | .Pp | |
525 | Enabling deduplication on an improperly-designed system can result in | |
526 | performance issues (slow IO and administrative operations). It can potentially | |
527 | lead to problems importing a pool due to memory exhaustion. Deduplication | |
528 | can consume significant processing power (CPU) and memory as well as generate | |
529 | additional disk IO. | |
530 | .Pp | |
531 | Before creating a pool with deduplication enabled, ensure that you have planned | |
532 | your hardware requirements appropriately and implemented appropriate recovery | |
533 | practices, such as regular backups. As an alternative to deduplication | |
534 | consider using | |
57858fb5 | 535 | .Sy compression=on , |
44f09cdc BB |
536 | as a less resource-intensive alternative. |
537 | .Ss Native Properties | |
538 | Properties are divided into two types, native properties and user-defined | |
539 | .Po or | |
540 | .Qq user | |
541 | .Pc | |
542 | properties. | |
543 | Native properties either export internal statistics or control ZFS behavior. | |
544 | In addition, native properties are either editable or read-only. | |
545 | User properties have no effect on ZFS behavior, but you can use them to annotate | |
546 | datasets in a way that is meaningful in your environment. | |
547 | For more information about user properties, see the | |
548 | .Sx User Properties | |
549 | section, below. | |
550 | .Pp | |
551 | Every dataset has a set of properties that export statistics about the dataset | |
552 | as well as control various behaviors. | |
553 | Properties are inherited from the parent unless overridden by the child. | |
554 | Some properties apply only to certain types of datasets | |
555 | .Pq file systems, volumes, or snapshots . | |
556 | .Pp | |
557 | The values of numeric properties can be specified using human-readable suffixes | |
558 | .Po for example, | |
559 | .Sy k , | |
560 | .Sy KB , | |
561 | .Sy M , | |
562 | .Sy Gb , | |
563 | and so forth, up to | |
564 | .Sy Z | |
565 | for zettabyte | |
566 | .Pc . | |
567 | The following are all valid | |
568 | .Pq and equal | |
569 | specifications: | |
570 | .Li 1536M, 1.5g, 1.50GB . | |
571 | .Pp | |
572 | The values of non-numeric properties are case sensitive and must be lowercase, | |
573 | except for | |
574 | .Sy mountpoint , | |
575 | .Sy sharenfs , | |
576 | and | |
577 | .Sy sharesmb . | |
578 | .Pp | |
579 | The following native properties consist of read-only statistics about the | |
580 | dataset. | |
581 | These properties can be neither set, nor inherited. | |
582 | Native properties apply to all dataset types unless otherwise noted. | |
583 | .Bl -tag -width "usedbyrefreservation" | |
584 | .It Sy available | |
585 | The amount of space available to the dataset and all its children, assuming that | |
586 | there is no other activity in the pool. | |
587 | Because space is shared within a pool, availability can be limited by any number | |
588 | of factors, including physical pool size, quotas, reservations, or other | |
589 | datasets within the pool. | |
590 | .Pp | |
591 | This property can also be referred to by its shortened column name, | |
592 | .Sy avail . | |
593 | .It Sy compressratio | |
594 | For non-snapshots, the compression ratio achieved for the | |
595 | .Sy used | |
596 | space of this dataset, expressed as a multiplier. | |
597 | The | |
598 | .Sy used | |
599 | property includes descendant datasets, and, for clones, does not include the | |
600 | space shared with the origin snapshot. | |
601 | For snapshots, the | |
602 | .Sy compressratio | |
603 | is the same as the | |
604 | .Sy refcompressratio | |
605 | property. | |
606 | Compression can be turned on by running: | |
607 | .Nm zfs Cm set Sy compression Ns = Ns Sy on Ar dataset . | |
608 | The default value is | |
609 | .Sy off . | |
610 | .It Sy createtxg | |
611 | The transaction group (txg) in which the dataset was created. Bookmarks have | |
612 | the same | |
613 | .Sy createtxg | |
614 | as the snapshot they are initially tied to. This property is suitable for | |
615 | ordering a list of snapshots, e.g. for incremental send and receive. | |
616 | .It Sy creation | |
058ac9ba | 617 | The time this dataset was created. |
44f09cdc BB |
618 | .It Sy clones |
619 | For snapshots, this property is a comma-separated list of filesystems or volumes | |
620 | which are clones of this snapshot. | |
621 | The clones' | |
622 | .Sy origin | |
623 | property is this snapshot. | |
624 | If the | |
625 | .Sy clones | |
626 | property is not empty, then this snapshot can not be destroyed | |
627 | .Po even with the | |
628 | .Fl r | |
629 | or | |
630 | .Fl f | |
631 | options | |
632 | .Pc . | |
633 | The roles of origin and clone can be swapped by promoting the clone with the | |
634 | .Nm zfs Cm promote | |
635 | command. | |
636 | .It Sy defer_destroy | |
637 | This property is | |
638 | .Sy on | |
639 | if the snapshot has been marked for deferred destroy by using the | |
640 | .Nm zfs Cm destroy Fl d | |
641 | command. | |
642 | Otherwise, the property is | |
643 | .Sy off . | |
b5256303 TC |
644 | .It Sy encryptionroot |
645 | For encrypted datasets, indicates where the dataset is currently inheriting its | |
646 | encryption key from. Loading or unloading a key for the | |
647 | .Sy encryptionroot | |
648 | will implicitly load / unload the key for any inheriting datasets (see | |
649 | .Nm zfs Cm load-key | |
650 | and | |
651 | .Nm zfs Cm unload-key | |
652 | for details). | |
653 | Clones will always share an | |
654 | encryption key with their origin. See the | |
655 | .Sx Encryption | |
656 | section for details. | |
44f09cdc BB |
657 | .It Sy filesystem_count |
658 | The total number of filesystems and volumes that exist under this location in | |
659 | the dataset tree. | |
660 | This value is only available when a | |
661 | .Sy filesystem_limit | |
662 | has been set somewhere in the tree under which the dataset resides. | |
b5256303 TC |
663 | .It Sy keystatus |
664 | Indicates if an encryption key is currently loaded into ZFS. The possible | |
665 | values are | |
666 | .Sy none , | |
667 | .Sy available , | |
668 | and | |
669 | .Sy unavailable . | |
670 | See | |
671 | .Nm zfs Cm load-key | |
672 | and | |
673 | .Nm zfs Cm unload-key . | |
44f09cdc BB |
674 | .It Sy guid |
675 | The 64 bit GUID of this dataset or bookmark which does not change over its | |
676 | entire lifetime. When a snapshot is sent to another pool, the received | |
677 | snapshot has the same GUID. Thus, the | |
678 | .Sy guid | |
679 | is suitable to identify a snapshot across pools. | |
680 | .It Sy logicalreferenced | |
681 | The amount of space that is | |
682 | .Qq logically | |
683 | accessible by this dataset. | |
684 | See the | |
685 | .Sy referenced | |
686 | property. | |
687 | The logical space ignores the effect of the | |
688 | .Sy compression | |
689 | and | |
690 | .Sy copies | |
691 | properties, giving a quantity closer to the amount of data that applications | |
692 | see. | |
693 | However, it does include space consumed by metadata. | |
694 | .Pp | |
24a64651 | 695 | This property can also be referred to by its shortened column name, |
44f09cdc BB |
696 | .Sy lrefer . |
697 | .It Sy logicalused | |
698 | The amount of space that is | |
699 | .Qq logically | |
700 | consumed by this dataset and all its descendents. | |
701 | See the | |
702 | .Sy used | |
703 | property. | |
704 | The logical space ignores the effect of the | |
705 | .Sy compression | |
706 | and | |
707 | .Sy copies | |
708 | properties, giving a quantity closer to the amount of data that applications | |
709 | see. | |
24a64651 | 710 | However, it does include space consumed by metadata. |
44f09cdc | 711 | .Pp |
24a64651 | 712 | This property can also be referred to by its shortened column name, |
44f09cdc BB |
713 | .Sy lused . |
714 | .It Sy mounted | |
715 | For file systems, indicates whether the file system is currently mounted. | |
716 | This property can be either | |
717 | .Sy yes | |
718 | or | |
719 | .Sy no . | |
a448a255 SD |
720 | .It Sy objsetid |
721 | A unique identifier for this dataset within the pool. Unlike the dataset's | |
722 | .Sy guid | |
723 | , the | |
724 | .Sy objsetid | |
725 | of a dataset is not transferred to other pools when the snapshot is copied | |
726 | with a send/receive operation. | |
727 | The | |
728 | .Sy objsetid | |
729 | can be reused (for a new datatset) after the dataset is deleted. | |
44f09cdc BB |
730 | .It Sy origin |
731 | For cloned file systems or volumes, the snapshot from which the clone was | |
732 | created. | |
733 | See also the | |
734 | .Sy clones | |
f5fc4aca | 735 | property. |
44f09cdc BB |
736 | .It Sy receive_resume_token |
737 | For filesystems or volumes which have saved partially-completed state from | |
738 | .Sy zfs receive -s , | |
739 | this opaque token can be provided to | |
740 | .Sy zfs send -t | |
741 | to resume and complete the | |
742 | .Sy zfs receive . | |
743 | .It Sy referenced | |
744 | The amount of data that is accessible by this dataset, which may or may not be | |
745 | shared with other datasets in the pool. | |
746 | When a snapshot or clone is created, it initially references the same amount of | |
747 | space as the file system or snapshot it was created from, since its contents are | |
748 | identical. | |
749 | .Pp | |
750 | This property can also be referred to by its shortened column name, | |
751 | .Sy refer . | |
752 | .It Sy refcompressratio | |
753 | The compression ratio achieved for the | |
754 | .Sy referenced | |
755 | space of this dataset, expressed as a multiplier. | |
756 | See also the | |
757 | .Sy compressratio | |
758 | property. | |
759 | .It Sy snapshot_count | |
760 | The total number of snapshots that exist under this location in the dataset | |
761 | tree. | |
762 | This value is only available when a | |
763 | .Sy snapshot_limit | |
764 | has been set somewhere in the tree under which the dataset resides. | |
765 | .It Sy type | |
766 | The type of dataset: | |
767 | .Sy filesystem , | |
768 | .Sy volume , | |
769 | or | |
770 | .Sy snapshot . | |
771 | .It Sy used | |
772 | The amount of space consumed by this dataset and all its descendents. | |
773 | This is the value that is checked against this dataset's quota and reservation. | |
774 | The space used does not include this dataset's reservation, but does take into | |
775 | account the reservations of any descendent datasets. | |
776 | The amount of space that a dataset consumes from its parent, as well as the | |
777 | amount of space that is freed if this dataset is recursively destroyed, is the | |
778 | greater of its space used and its reservation. | |
779 | .Pp | |
780 | The used space of a snapshot | |
781 | .Po see the | |
782 | .Sx Snapshots | |
783 | section | |
784 | .Pc | |
785 | is space that is referenced exclusively by this snapshot. | |
786 | If this snapshot is destroyed, the amount of | |
787 | .Sy used | |
788 | space will be freed. | |
789 | Space that is shared by multiple snapshots isn't accounted for in this metric. | |
790 | When a snapshot is destroyed, space that was previously shared with this | |
791 | snapshot can become unique to snapshots adjacent to it, thus changing the used | |
792 | space of those snapshots. | |
793 | The used space of the latest snapshot can also be affected by changes in the | |
794 | file system. | |
795 | Note that the | |
796 | .Sy used | |
797 | space of a snapshot is a subset of the | |
798 | .Sy written | |
799 | space of the snapshot. | |
800 | .Pp | |
801 | The amount of space used, available, or referenced does not take into account | |
802 | pending changes. | |
803 | Pending changes are generally accounted for within a few seconds. | |
804 | Committing a change to a disk using | |
805 | .Xr fsync 2 | |
806 | or | |
807 | .Dv O_SYNC | |
808 | does not necessarily guarantee that the space usage information is updated | |
809 | immediately. | |
810 | .It Sy usedby* | |
811 | The | |
812 | .Sy usedby* | |
813 | properties decompose the | |
814 | .Sy used | |
815 | properties into the various reasons that space is used. | |
816 | Specifically, | |
817 | .Sy used No = | |
818 | .Sy usedbychildren No + | |
819 | .Sy usedbydataset No + | |
820 | .Sy usedbyrefreservation No + | |
821 | .Sy usedbysnapshots . | |
822 | These properties are only available for datasets created on | |
823 | .Nm zpool | |
824 | .Qo version 13 Qc | |
825 | pools. | |
826 | .It Sy usedbychildren | |
827 | The amount of space used by children of this dataset, which would be freed if | |
828 | all the dataset's children were destroyed. | |
829 | .It Sy usedbydataset | |
830 | The amount of space used by this dataset itself, which would be freed if the | |
831 | dataset were destroyed | |
832 | .Po after first removing any | |
833 | .Sy refreservation | |
834 | and destroying any necessary snapshots or descendents | |
835 | .Pc . | |
836 | .It Sy usedbyrefreservation | |
837 | The amount of space used by a | |
838 | .Sy refreservation | |
839 | set on this dataset, which would be freed if the | |
840 | .Sy refreservation | |
841 | was removed. | |
842 | .It Sy usedbysnapshots | |
843 | The amount of space consumed by snapshots of this dataset. | |
844 | In particular, it is the amount of space that would be freed if all of this | |
845 | dataset's snapshots were destroyed. | |
846 | Note that this is not simply the sum of the snapshots' | |
847 | .Sy used | |
848 | properties because space can be shared by multiple snapshots. | |
849 | .It Sy userused Ns @ Ns Em user | |
850 | The amount of space consumed by the specified user in this dataset. | |
851 | Space is charged to the owner of each file, as displayed by | |
852 | .Nm ls Fl l . | |
853 | The amount of space charged is displayed by | |
854 | .Nm du | |
855 | and | |
856 | .Nm ls Fl s . | |
857 | See the | |
858 | .Nm zfs Cm userspace | |
859 | subcommand for more information. | |
860 | .Pp | |
861 | Unprivileged users can access only their own space usage. | |
862 | The root user, or a user who has been granted the | |
863 | .Sy userused | |
864 | privilege with | |
865 | .Nm zfs Cm allow , | |
866 | can access everyone's usage. | |
867 | .Pp | |
868 | The | |
869 | .Sy userused Ns @ Ns Em ... | |
870 | properties are not displayed by | |
871 | .Nm zfs Cm get Sy all . | |
872 | The user's name must be appended after the @ symbol, using one of the following | |
873 | forms: | |
874 | .Bl -bullet -width "" | |
875 | .It | |
876 | .Em POSIX name | |
877 | .Po for example, | |
878 | .Sy joe | |
879 | .Pc | |
880 | .It | |
881 | .Em POSIX numeric ID | |
882 | .Po for example, | |
883 | .Sy 789 | |
884 | .Pc | |
885 | .It | |
886 | .Em SID name | |
887 | .Po for example, | |
888 | .Sy joe.smith@mydomain | |
889 | .Pc | |
890 | .It | |
891 | .Em SID numeric ID | |
892 | .Po for example, | |
893 | .Sy S-1-123-456-789 | |
894 | .Pc | |
895 | .El | |
896 | .Pp | |
f974e414 | 897 | Files created on Linux always have POSIX owners. |
44f09cdc BB |
898 | .It Sy userobjused Ns @ Ns Em user |
899 | The | |
900 | .Sy userobjused | |
901 | property is similar to | |
902 | .Sy userused | |
903 | but instead it counts the number of objects consumed by a user. This property | |
904 | counts all objects allocated on behalf of the user, it may differ from the | |
905 | results of system tools such as | |
906 | .Nm df Fl i . | |
907 | .Pp | |
908 | When the property | |
909 | .Sy xattr=on | |
910 | is set on a file system additional objects will be created per-file to store | |
911 | extended attributes. These additional objects are reflected in the | |
912 | .Sy userobjused | |
913 | value and are counted against the user's | |
914 | .Sy userobjquota . | |
915 | When a file system is configured to use | |
916 | .Sy xattr=sa | |
917 | no additional internal objects are normally required. | |
918 | .It Sy userrefs | |
919 | This property is set to the number of user holds on this snapshot. | |
920 | User holds are set by using the | |
921 | .Nm zfs Cm hold | |
922 | command. | |
923 | .It Sy groupused Ns @ Ns Em group | |
924 | The amount of space consumed by the specified group in this dataset. | |
925 | Space is charged to the group of each file, as displayed by | |
926 | .Nm ls Fl l . | |
927 | See the | |
928 | .Sy userused Ns @ Ns Em user | |
929 | property for more information. | |
930 | .Pp | |
931 | Unprivileged users can only access their own groups' space usage. | |
932 | The root user, or a user who has been granted the | |
933 | .Sy groupused | |
934 | privilege with | |
935 | .Nm zfs Cm allow , | |
936 | can access all groups' usage. | |
937 | .It Sy groupobjused Ns @ Ns Em group | |
938 | The number of objects consumed by the specified group in this dataset. | |
939 | Multiple objects may be charged to the group for each file when extended | |
940 | attributes are in use. See the | |
941 | .Sy userobjused Ns @ Ns Em user | |
942 | property for more information. | |
943 | .Pp | |
944 | Unprivileged users can only access their own groups' space usage. | |
945 | The root user, or a user who has been granted the | |
946 | .Sy groupobjused | |
947 | privilege with | |
948 | .Nm zfs Cm allow , | |
949 | can access all groups' usage. | |
9c5167d1 NF |
950 | .It Sy projectused Ns @ Ns Em project |
951 | The amount of space consumed by the specified project in this dataset. Project | |
952 | is identified via the project identifier (ID) that is object-based numeral | |
953 | attribute. An object can inherit the project ID from its parent object (if the | |
954 | parent has the flag of inherit project ID that can be set and changed via | |
955 | .Nm chattr Fl /+P | |
956 | or | |
957 | .Nm zfs project Fl s ) | |
958 | when being created. The privileged user can set and change object's project | |
959 | ID via | |
960 | .Nm chattr Fl p | |
961 | or | |
962 | .Nm zfs project Fl s | |
963 | anytime. Space is charged to the project of each file, as displayed by | |
964 | .Nm lsattr Fl p | |
965 | or | |
966 | .Nm zfs project . | |
967 | See the | |
968 | .Sy userused Ns @ Ns Em user | |
969 | property for more information. | |
970 | .Pp | |
971 | The root user, or a user who has been granted the | |
972 | .Sy projectused | |
973 | privilege with | |
974 | .Nm zfs allow , | |
975 | can access all projects' usage. | |
976 | .It Sy projectobjused Ns @ Ns Em project | |
977 | The | |
978 | .Sy projectobjused | |
979 | is similar to | |
980 | .Sy projectused | |
981 | but instead it counts the number of objects consumed by project. When the | |
982 | property | |
983 | .Sy xattr=on | |
984 | is set on a fileset, ZFS will create additional objects per-file to store | |
985 | extended attributes. These additional objects are reflected in the | |
986 | .Sy projectobjused | |
987 | value and are counted against the project's | |
988 | .Sy projectobjquota . | |
989 | When a filesystem is configured to use | |
990 | .Sy xattr=sa | |
991 | no additional internal objects are required. See the | |
992 | .Sy userobjused Ns @ Ns Em user | |
993 | property for more information. | |
994 | .Pp | |
995 | The root user, or a user who has been granted the | |
996 | .Sy projectobjused | |
997 | privilege with | |
998 | .Nm zfs allow , | |
999 | can access all projects' objects usage. | |
44f09cdc BB |
1000 | .It Sy volblocksize |
1001 | For volumes, specifies the block size of the volume. | |
1002 | The | |
1003 | .Sy blocksize | |
1004 | cannot be changed once the volume has been written, so it should be set at | |
1005 | volume creation time. | |
1006 | The default | |
1007 | .Sy blocksize | |
1008 | for volumes is 8 Kbytes. | |
1009 | Any power of 2 from 512 bytes to 128 Kbytes is valid. | |
1010 | .Pp | |
1011 | This property can also be referred to by its shortened column name, | |
1012 | .Sy volblock . | |
1013 | .It Sy written | |
1014 | The amount of space | |
1015 | .Sy referenced | |
1016 | by this dataset, that was written since the previous snapshot | |
1017 | .Pq i.e. that is not referenced by the previous snapshot . | |
1018 | .It Sy written Ns @ Ns Em snapshot | |
1019 | The amount of | |
1020 | .Sy referenced | |
1021 | space written to this dataset since the specified snapshot. | |
1022 | This is the space that is referenced by this dataset but was not referenced by | |
1023 | the specified snapshot. | |
1024 | .Pp | |
1025 | The | |
1026 | .Em snapshot | |
1027 | may be specified as a short snapshot name | |
1028 | .Po just the part after the | |
1029 | .Sy @ | |
1030 | .Pc , | |
1031 | in which case it will be interpreted as a snapshot in the same filesystem as | |
1032 | this dataset. | |
1033 | The | |
1034 | .Em snapshot | |
1035 | may be a full snapshot name | |
1036 | .Po Em filesystem Ns @ Ns Em snapshot Pc , | |
1037 | which for clones may be a snapshot in the origin's filesystem | |
1038 | .Pq or the origin of the origin's filesystem, etc. | |
1039 | .El | |
1040 | .Pp | |
1041 | The following native properties can be used to change the behavior of a ZFS | |
1042 | dataset. | |
1043 | .Bl -tag -width "" | |
1044 | .It Xo | |
1045 | .Sy aclinherit Ns = Ns Sy discard Ns | Ns Sy noallow Ns | Ns | |
1046 | .Sy restricted Ns | Ns Sy passthrough Ns | Ns Sy passthrough-x | |
1047 | .Xc | |
1048 | Controls how ACEs are inherited when files and directories are created. | |
1049 | .Bl -tag -width "passthrough-x" | |
1050 | .It Sy discard | |
1051 | does not inherit any ACEs. | |
1052 | .It Sy noallow | |
1053 | only inherits inheritable ACEs that specify | |
1054 | .Qq deny | |
1055 | permissions. | |
1056 | .It Sy restricted | |
1057 | default, removes the | |
1058 | .Sy write_acl | |
1059 | and | |
1060 | .Sy write_owner | |
1061 | permissions when the ACE is inherited. | |
1062 | .It Sy passthrough | |
1063 | inherits all inheritable ACEs without any modifications. | |
1064 | .It Sy passthrough-x | |
1065 | same meaning as | |
1066 | .Sy passthrough , | |
1067 | except that the | |
1068 | .Sy owner@ , | |
1069 | .Sy group@ , | |
1070 | and | |
1071 | .Sy everyone@ | |
1072 | ACEs inherit the execute permission only if the file creation mode also requests | |
1073 | the execute bit. | |
1074 | .El | |
1075 | .Pp | |
1076 | When the property value is set to | |
1077 | .Sy passthrough , | |
1078 | files are created with a mode determined by the inheritable ACEs. | |
1079 | If no inheritable ACEs exist that affect the mode, then the mode is set in | |
1080 | accordance to the requested mode from the application. | |
1081 | .Pp | |
1082 | The | |
1083 | .Sy aclinherit | |
06f3fc2a | 1084 | property does not apply to POSIX ACLs. |
44f09cdc BB |
1085 | .It Sy acltype Ns = Ns Sy off Ns | Ns Sy noacl Ns | Ns Sy posixacl |
1086 | Controls whether ACLs are enabled and if so what type of ACL to use. | |
1087 | .Bl -tag -width "posixacl" | |
1088 | .It Sy off | |
1089 | default, when a file system has the | |
1090 | .Sy acltype | |
1091 | property set to off then ACLs are disabled. | |
1092 | .It Sy noacl | |
1093 | an alias for | |
1094 | .Sy off | |
1095 | .It Sy posixacl | |
06f3fc2a RL |
1096 | indicates POSIX ACLs should be used. POSIX ACLs are specific to Linux and are |
1097 | not functional on other platforms. POSIX ACLs are stored as an extended | |
44f09cdc BB |
1098 | attribute and therefore will not overwrite any existing NFSv4 ACLs which |
1099 | may be set. | |
1100 | .El | |
1101 | .Pp | |
1102 | To obtain the best performance when setting | |
1103 | .Sy posixacl | |
1104 | users are strongly encouraged to set the | |
1105 | .Sy xattr=sa | |
06f3fc2a RL |
1106 | property. This will result in the POSIX ACL being stored more efficiently on |
1107 | disk. But as a consequence, all new extended attributes will only be | |
44f09cdc BB |
1108 | accessible from OpenZFS implementations which support the |
1109 | .Sy xattr=sa | |
1110 | property. See the | |
1111 | .Sy xattr | |
1112 | property for more details. | |
1113 | .It Sy atime Ns = Ns Sy on Ns | Ns Sy off | |
1114 | Controls whether the access time for files is updated when they are read. | |
1115 | Turning this property off avoids producing write traffic when reading files and | |
1116 | can result in significant performance gains, though it might confuse mailers | |
1117 | and other similar utilities. The values | |
1118 | .Sy on | |
1119 | and | |
1120 | .Sy off | |
1121 | are equivalent to the | |
1122 | .Sy atime | |
1123 | and | |
1124 | .Sy noatime | |
1125 | mount options. The default value is | |
1126 | .Sy on . | |
1127 | See also | |
1128 | .Sy relatime | |
1129 | below. | |
1130 | .It Sy canmount Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy noauto | |
1131 | If this property is set to | |
1132 | .Sy off , | |
1133 | the file system cannot be mounted, and is ignored by | |
1134 | .Nm zfs Cm mount Fl a . | |
1135 | Setting this property to | |
1136 | .Sy off | |
1137 | is similar to setting the | |
1138 | .Sy mountpoint | |
1139 | property to | |
1140 | .Sy none , | |
1141 | except that the dataset still has a normal | |
1142 | .Sy mountpoint | |
1143 | property, which can be inherited. | |
1144 | Setting this property to | |
1145 | .Sy off | |
1146 | allows datasets to be used solely as a mechanism to inherit properties. | |
1147 | One example of setting | |
1148 | .Sy canmount Ns = Ns Sy off | |
1149 | is to have two datasets with the same | |
1150 | .Sy mountpoint , | |
1151 | so that the children of both datasets appear in the same directory, but might | |
1152 | have different inherited characteristics. | |
1153 | .Pp | |
1154 | When set to | |
1155 | .Sy noauto , | |
1156 | a dataset can only be mounted and unmounted explicitly. | |
1157 | The dataset is not mounted automatically when the dataset is created or | |
1158 | imported, nor is it mounted by the | |
1159 | .Nm zfs Cm mount Fl a | |
1160 | command or unmounted by the | |
1161 | .Nm zfs Cm unmount Fl a | |
1162 | command. | |
1163 | .Pp | |
1164 | This property is not inherited. | |
1165 | .It Xo | |
1166 | .Sy checksum Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy fletcher2 Ns | Ns | |
1167 | .Sy fletcher4 Ns | Ns Sy sha256 Ns | Ns Sy noparity Ns | Ns | |
1168 | .Sy sha512 Ns | Ns Sy skein Ns | Ns Sy edonr | |
1169 | .Xc | |
1170 | Controls the checksum used to verify data integrity. | |
1171 | The default value is | |
1172 | .Sy on , | |
1173 | which automatically selects an appropriate algorithm | |
1174 | .Po currently, | |
1175 | .Sy fletcher4 , | |
1176 | but this may change in future releases | |
1177 | .Pc . | |
1178 | The value | |
1179 | .Sy off | |
1180 | disables integrity checking on user data. | |
1181 | The value | |
1182 | .Sy noparity | |
1183 | not only disables integrity but also disables maintaining parity for user data. | |
3c67d83a | 1184 | This setting is used internally by a dump device residing on a RAID-Z pool and |
44f09cdc BB |
1185 | should not be used by any other dataset. |
1186 | Disabling checksums is | |
1187 | .Sy NOT | |
1188 | a recommended practice. | |
1189 | .Pp | |
1190 | The | |
1191 | .Sy sha512 , | |
1192 | .Sy skein , | |
1193 | and | |
1194 | .Sy edonr | |
1195 | checksum algorithms require enabling the appropriate features on the pool. | |
6c0f78f8 RL |
1196 | These pool features are not supported by GRUB and must not be used on the |
1197 | pool if GRUB needs to access the pool (e.g. for /boot). | |
1198 | .Pp | |
44f09cdc BB |
1199 | Please see |
1200 | .Xr zpool-features 5 | |
1201 | for more information on these algorithms. | |
1202 | .Pp | |
058ac9ba | 1203 | Changing this property affects only newly-written data. |
44f09cdc BB |
1204 | .It Xo |
1205 | .Sy compression Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy gzip Ns | Ns | |
1206 | .Sy gzip- Ns Em N Ns | Ns Sy lz4 Ns | Ns Sy lzjb Ns | Ns Sy zle | |
1207 | .Xc | |
99197f03 | 1208 | Controls the compression algorithm used for this dataset. |
44f09cdc BB |
1209 | .Pp |
1210 | Setting compression to | |
1211 | .Sy on | |
1212 | indicates that the current default compression algorithm should be used. | |
1213 | The default balances compression and decompression speed, with compression ratio | |
1214 | and is expected to work well on a wide variety of workloads. | |
1215 | Unlike all other settings for this property, | |
1216 | .Sy on | |
1217 | does not select a fixed compression type. | |
1218 | As new compression algorithms are added to ZFS and enabled on a pool, the | |
1219 | default compression algorithm may change. | |
1220 | The current default compression algorithm is either | |
1221 | .Sy lzjb | |
1222 | or, if the | |
1223 | .Sy lz4_compress | |
1224 | feature is enabled, | |
1225 | .Sy lz4 . | |
1226 | .Pp | |
1227 | The | |
1228 | .Sy lz4 | |
1229 | compression algorithm is a high-performance replacement for the | |
1230 | .Sy lzjb | |
1231 | algorithm. | |
1232 | It features significantly faster compression and decompression, as well as a | |
1233 | moderately higher compression ratio than | |
1234 | .Sy lzjb , | |
1235 | but can only be used on pools with the | |
1236 | .Sy lz4_compress | |
1237 | feature set to | |
1238 | .Sy enabled . | |
1239 | See | |
1240 | .Xr zpool-features 5 | |
1241 | for details on ZFS feature flags and the | |
1242 | .Sy lz4_compress | |
1243 | feature. | |
1244 | .Pp | |
1245 | The | |
1246 | .Sy lzjb | |
1247 | compression algorithm is optimized for performance while providing decent data | |
1248 | compression. | |
1249 | .Pp | |
1250 | The | |
1251 | .Sy gzip | |
1252 | compression algorithm uses the same compression as the | |
1253 | .Xr gzip 1 | |
1254 | command. | |
1255 | You can specify the | |
1256 | .Sy gzip | |
1257 | level by using the value | |
1258 | .Sy gzip- Ns Em N , | |
1259 | where | |
1260 | .Em N | |
1261 | is an integer from 1 | |
1262 | .Pq fastest | |
1263 | to 9 | |
1264 | .Pq best compression ratio . | |
1265 | Currently, | |
1266 | .Sy gzip | |
1267 | is equivalent to | |
1268 | .Sy gzip-6 | |
1269 | .Po which is also the default for | |
1270 | .Xr gzip 1 | |
1271 | .Pc . | |
1272 | .Pp | |
1273 | The | |
1274 | .Sy zle | |
1275 | compression algorithm compresses runs of zeros. | |
1276 | .Pp | |
99197f03 | 1277 | This property can also be referred to by its shortened column name |
44f09cdc BB |
1278 | .Sy compress . |
1279 | Changing this property affects only newly-written data. | |
ba7b05cb D |
1280 | .Pp |
1281 | When any setting except | |
1282 | .Sy off | |
1283 | is selected, compression will explicitly check for blocks consisting of only | |
1284 | zeroes (the NUL byte). When a zero-filled block is detected, it is stored as | |
1285 | a hole and not compressed using the indicated compression algorithm. | |
1286 | .Pp | |
1287 | Any block being compressed must be no larger than 7/8 of its original size | |
1288 | after compression, otherwise the compression will not be considered worthwhile | |
1289 | and the block saved uncompressed. Note that when the logical block is less than | |
1290 | 8 times the disk sector size this effectively reduces the necessary compression | |
1291 | ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2 | |
1292 | or less of their original size. | |
44f09cdc BB |
1293 | .It Xo |
1294 | .Sy context Ns = Ns Sy none Ns | Ns | |
1295 | .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level | |
1296 | .Xc | |
1297 | This flag sets the SELinux context for all files in the file system under | |
1298 | a mount point for that file system. See | |
1299 | .Xr selinux 8 | |
1300 | for more information. | |
1301 | .It Xo | |
1302 | .Sy fscontext Ns = Ns Sy none Ns | Ns | |
1303 | .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level | |
1304 | .Xc | |
1305 | This flag sets the SELinux context for the file system file system being | |
1306 | mounted. See | |
1307 | .Xr selinux 8 | |
1308 | for more information. | |
1309 | .It Xo | |
1310 | .Sy defcontext Ns = Ns Sy none Ns | Ns | |
1311 | .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level | |
1312 | .Xc | |
1313 | This flag sets the SELinux default context for unlabeled files. See | |
1314 | .Xr selinux 8 | |
1315 | for more information. | |
1316 | .It Xo | |
1317 | .Sy rootcontext Ns = Ns Sy none Ns | Ns | |
1318 | .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level | |
1319 | .Xc | |
1320 | This flag sets the SELinux context for the root inode of the file system. See | |
1321 | .Xr selinux 8 | |
1322 | for more information. | |
1323 | .It Sy copies Ns = Ns Sy 1 Ns | Ns Sy 2 Ns | Ns Sy 3 | |
1324 | Controls the number of copies of data stored for this dataset. | |
1325 | These copies are in addition to any redundancy provided by the pool, for | |
1326 | example, mirroring or RAID-Z. | |
1327 | The copies are stored on different disks, if possible. | |
1328 | The space used by multiple copies is charged to the associated file and dataset, | |
1329 | changing the | |
1330 | .Sy used | |
1331 | property and counting against quotas and reservations. | |
1332 | .Pp | |
8fd888ba | 1333 | Changing this property only affects newly-written data. |
44f09cdc BB |
1334 | Therefore, set this property at file system creation time by using the |
1335 | .Fl o Sy copies Ns = Ns Ar N | |
1336 | option. | |
1337 | .Pp | |
1338 | Remember that ZFS will not import a pool with a missing top-level vdev. Do | |
1339 | .Sy NOT | |
1340 | create, for example a two-disk striped pool and set | |
1341 | .Sy copies=2 | |
1342 | on some datasets thinking you have setup redundancy for them. When a disk | |
1343 | fails you will not be able to import the pool and will have lost all of your | |
1344 | data. | |
6e81f9b2 RL |
1345 | .Pp |
1346 | Encrypted datasets may not have | |
1347 | .Sy copies Ns = Ns Em 3 | |
1348 | since the implementation stores some encryption metadata where the third copy | |
1349 | would normally be. | |
44f09cdc BB |
1350 | .It Sy devices Ns = Ns Sy on Ns | Ns Sy off |
1351 | Controls whether device nodes can be opened on this file system. | |
1352 | The default value is | |
1353 | .Sy on . | |
1354 | The values | |
1355 | .Sy on | |
1356 | and | |
1357 | .Sy off | |
1358 | are equivalent to the | |
1359 | .Sy dev | |
1360 | and | |
1361 | .Sy nodev | |
1362 | mount options. | |
1363 | .It Xo | |
dfb1ad02 D |
1364 | .Sy dedup Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy verify Ns | Ns |
1365 | .Sy sha256[,verify] Ns | Ns Sy sha512[,verify] Ns | Ns Sy skein[,verify] Ns | Ns | |
1366 | .Sy edonr,verify | |
1367 | .Xc | |
1368 | Configures deduplication for a dataset. The default value is | |
1369 | .Sy off . | |
1370 | The default deduplication checksum is | |
1371 | .Sy sha256 | |
1372 | (this may change in the future). When | |
1373 | .Sy dedup | |
1374 | is enabled, the checksum defined here overrides the | |
1375 | .Sy checksum | |
1376 | property. Setting the value to | |
1377 | .Sy verify | |
1378 | has the same effect as the setting | |
1379 | .Sy sha256,verify. | |
1380 | .Pp | |
1381 | If set to | |
1382 | .Sy verify , | |
1383 | ZFS will do a byte-to-byte comparsion in case of two blocks having the same | |
1384 | signature to make sure the block contents are identical. Specifying | |
1385 | .Sy verify | |
1386 | is mandatory for the | |
1387 | .Sy edonr | |
1388 | algorithm. | |
1389 | .Pp | |
1390 | Unless necessary, deduplication should NOT be enabled on a system. See | |
1391 | .Sx Deduplication | |
1392 | above. | |
1393 | .It Xo | |
44f09cdc BB |
1394 | .Sy dnodesize Ns = Ns Sy legacy Ns | Ns Sy auto Ns | Ns Sy 1k Ns | Ns |
1395 | .Sy 2k Ns | Ns Sy 4k Ns | Ns Sy 8k Ns | Ns Sy 16k | |
1396 | .Xc | |
1397 | Specifies a compatibility mode or literal value for the size of dnodes in the | |
1398 | file system. The default value is | |
1399 | .Sy legacy . | |
1400 | Setting this property to a value other than | |
1401 | .Sy legacy | |
1402 | requires the large_dnode pool feature to be enabled. | |
1403 | .Pp | |
1404 | Consider setting | |
1405 | .Sy dnodesize | |
1406 | to | |
1407 | .Sy auto | |
1408 | if the dataset uses the | |
1409 | .Sy xattr=sa | |
1410 | property setting and the workload makes heavy use of extended attributes. This | |
1411 | may be applicable to SELinux-enabled systems, Lustre servers, and Samba | |
1412 | servers, for example. Literal values are supported for cases where the optimal | |
1413 | size is known in advance and for performance testing. | |
1414 | .Pp | |
1415 | Leave | |
1416 | .Sy dnodesize | |
1417 | set to | |
1418 | .Sy legacy | |
1419 | if you need to receive a send stream of this dataset on a pool that doesn't | |
1420 | enable the large_dnode feature, or if you need to import this pool on a system | |
1421 | that doesn't support the large_dnode feature. | |
1422 | .Pp | |
50c957f7 | 1423 | This property can also be referred to by its shortened column name, |
44f09cdc | 1424 | .Sy dnsize . |
b5256303 TC |
1425 | .It Xo |
1426 | .Sy encryption Ns = Ns Sy off Ns | Ns Sy on Ns | Ns Sy aes-128-ccm Ns | Ns | |
1427 | .Sy aes-192-ccm Ns | Ns Sy aes-256-ccm Ns | Ns Sy aes-128-gcm Ns | Ns | |
1428 | .Sy aes-192-gcm Ns | Ns Sy aes-256-gcm | |
1429 | .Xc | |
1430 | Controls the encryption cipher suite (block cipher, key length, and mode) used | |
1431 | for this dataset. Requires the | |
1432 | .Sy encryption | |
1433 | feature to be enabled on the pool. | |
1434 | Requires a | |
1435 | .Sy keyformat | |
1436 | to be set at dataset creation time. | |
1437 | .Pp | |
1438 | Selecting | |
1439 | .Sy encryption Ns = Ns Sy on | |
1440 | when creating a dataset indicates that the default encryption suite will be | |
1441 | selected, which is currently | |
1442 | .Sy aes-256-ccm . | |
1443 | In order to provide consistent data protection, encryption must be specified at | |
1444 | dataset creation time and it cannot be changed afterwards. | |
1445 | .Pp | |
1446 | For more details and caveats about encryption see the | |
1447 | .Sy Encryption | |
1448 | section. | |
1449 | .It Sy keyformat Ns = Ns Sy raw Ns | Ns Sy hex Ns | Ns Sy passphrase | |
1450 | Controls what format the user's encryption key will be provided as. This | |
1451 | property is only set when the dataset is encrypted. | |
1452 | .Pp | |
1453 | Raw keys and hex keys must be 32 bytes long (regardless of the chosen | |
1454 | encryption suite) and must be randomly generated. A raw key can be generated | |
1455 | with the following command: | |
1456 | .Bd -literal | |
1457 | # dd if=/dev/urandom of=/path/to/output/key bs=32 count=1 | |
1458 | .Ed | |
1459 | .Pp | |
1460 | Passphrases must be between 8 and 512 bytes long and will be processed through | |
1461 | PBKDF2 before being used (see the | |
1462 | .Sy pbkdf2iters | |
1463 | property). Even though the | |
1464 | encryption suite cannot be changed after dataset creation, the keyformat can be | |
1465 | with | |
1466 | .Nm zfs Cm change-key . | |
1467 | .It Xo | |
1468 | .Sy keylocation Ns = Ns Sy prompt Ns | Ns Sy file:// Ns Em </absolute/file/path> | |
1469 | .Xc | |
1470 | Controls where the user's encryption key will be loaded from by default for | |
1471 | commands such as | |
1472 | .Nm zfs Cm load-key | |
1473 | and | |
7106b236 AR |
1474 | .Nm zfs Cm mount Cm -l . |
1475 | This property is only set for encrypted datasets which are encryption roots. If | |
1476 | unspecified, the default is | |
b5256303 TC |
1477 | .Sy prompt. |
1478 | .Pp | |
1479 | Even though the encryption suite cannot be changed after dataset creation, the | |
1480 | keylocation can be with either | |
1481 | .Nm zfs Cm set | |
1482 | or | |
1483 | .Nm zfs Cm change-key . | |
1484 | If | |
1485 | .Sy prompt | |
1486 | is selected ZFS will ask for the key at the command prompt when it is required | |
1487 | to access the encrypted data (see | |
1488 | .Nm zfs Cm load-key | |
1489 | for details). This setting will also allow the key to be passed in via STDIN, | |
1490 | but users should be careful not to place keys which should be kept secret on | |
1491 | the command line. If a file URI is selected, the key will be loaded from the | |
1492 | specified absolute file path. | |
1493 | .It Sy pbkdf2iters Ns = Ns Ar iterations | |
1494 | Controls the number of PBKDF2 iterations that a | |
1495 | .Sy passphrase | |
1496 | encryption key should be run through when processing it into an encryption key. | |
1497 | This property is only defined when encryption is enabled and a keyformat of | |
1498 | .Sy passphrase | |
1499 | is selected. The goal of PBKDF2 is to significantly increase the | |
1500 | computational difficulty needed to brute force a user's passphrase. This is | |
1501 | accomplished by forcing the attacker to run each passphrase through a | |
1502 | computationally expensive hashing function many times before they arrive at the | |
1503 | resulting key. A user who actually knows the passphrase will only have to pay | |
1504 | this cost once. As CPUs become better at processing, this number should be | |
1505 | raised to ensure that a brute force attack is still not possible. The current | |
1506 | default is | |
1507 | .Sy 350000 | |
1508 | and the minimum is | |
1509 | .Sy 100000 . | |
1510 | This property may be changed with | |
1511 | .Nm zfs Cm change-key . | |
44f09cdc BB |
1512 | .It Sy exec Ns = Ns Sy on Ns | Ns Sy off |
1513 | Controls whether processes can be executed from within this file system. | |
1514 | The default value is | |
1515 | .Sy on . | |
1516 | The values | |
1517 | .Sy on | |
1518 | and | |
1519 | .Sy off | |
1520 | are equivalent to the | |
1521 | .Sy exec | |
1522 | and | |
1523 | .Sy noexec | |
1524 | mount options. | |
1525 | .It Sy filesystem_limit Ns = Ns Em count Ns | Ns Sy none | |
788eb90c | 1526 | Limits the number of filesystems and volumes that can exist under this point in |
44f09cdc BB |
1527 | the dataset tree. |
1528 | The limit is not enforced if the user is allowed to change the limit. | |
1529 | Setting a | |
1530 | .Sy filesystem_limit | |
1531 | to | |
1532 | .Sy on | |
1533 | a descendent of a filesystem that already has a | |
1534 | .Sy filesystem_limit | |
1535 | does not override the ancestor's | |
1536 | .Sy filesystem_limit , | |
1537 | but rather imposes an additional limit. | |
1538 | This feature must be enabled to be used | |
1539 | .Po see | |
1540 | .Xr zpool-features 5 | |
1541 | .Pc . | |
cc99f275 DB |
1542 | .It Sy special_small_blocks Ns = Ns Em size |
1543 | This value represents the threshold block size for including small file | |
44170969 | 1544 | blocks into the special allocation class. Blocks smaller than or equal to this |
1545 | value will be assigned to the special allocation class while greater blocks | |
1546 | will be assigned to the regular class. Valid values are zero or a power of two | |
1547 | from 512B up to 128K. The default size is 0 which means no small file blocks | |
1548 | will be allocated in the special class. | |
cc99f275 DB |
1549 | .Pp |
1550 | Before setting this property, a special class vdev must be added to the | |
1551 | pool. See | |
1552 | .Xr zpool 8 | |
1553 | for more details on the special allocation class. | |
44f09cdc BB |
1554 | .It Sy mountpoint Ns = Ns Pa path Ns | Ns Sy none Ns | Ns Sy legacy |
1555 | Controls the mount point used for this file system. | |
1556 | See the | |
1557 | .Sx Mount Points | |
1558 | section for more information on how this property is used. | |
1559 | .Pp | |
1560 | When the | |
1561 | .Sy mountpoint | |
1562 | property is changed for a file system, the file system and any children that | |
1563 | inherit the mount point are unmounted. | |
1564 | If the new value is | |
1565 | .Sy legacy , | |
1566 | then they remain unmounted. | |
1567 | Otherwise, they are automatically remounted in the new location if the property | |
1568 | was previously | |
1569 | .Sy legacy | |
1570 | or | |
1571 | .Sy none , | |
1572 | or if they were mounted before the property was changed. | |
1573 | In addition, any shared file systems are unshared and shared in the new | |
1574 | location. | |
1575 | .It Sy nbmand Ns = Ns Sy on Ns | Ns Sy off | |
1576 | Controls whether the file system should be mounted with | |
1577 | .Sy nbmand | |
1578 | .Pq Non Blocking mandatory locks . | |
1579 | This is used for SMB clients. | |
1580 | Changes to this property only take effect when the file system is umounted and | |
1581 | remounted. | |
1582 | See | |
1583 | .Xr mount 8 | |
1584 | for more information on | |
1585 | .Sy nbmand | |
1586 | mounts. This property is not used on Linux. | |
1587 | .It Sy overlay Ns = Ns Sy off Ns | Ns Sy on | |
1588 | Allow mounting on a busy directory or a directory which already contains | |
1589 | files or directories. This is the default mount behavior for Linux file systems. | |
1590 | For consistency with OpenZFS on other platforms overlay mounts are | |
1591 | .Sy off | |
1592 | by default. Set to | |
1593 | .Sy on | |
1594 | to enable overlay mounts. | |
1595 | .It Sy primarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata | |
1596 | Controls what is cached in the primary cache | |
1597 | .Pq ARC . | |
1598 | If this property is set to | |
1599 | .Sy all , | |
1600 | then both user data and metadata is cached. | |
1601 | If this property is set to | |
1602 | .Sy none , | |
1603 | then neither user data nor metadata is cached. | |
1604 | If this property is set to | |
1605 | .Sy metadata , | |
1606 | then only metadata is cached. | |
1607 | The default value is | |
1608 | .Sy all . | |
1609 | .It Sy quota Ns = Ns Em size Ns | Ns Sy none | |
1610 | Limits the amount of space a dataset and its descendents can consume. | |
1611 | This property enforces a hard limit on the amount of space used. | |
1612 | This includes all space consumed by descendents, including file systems and | |
1613 | snapshots. | |
1614 | Setting a quota on a descendent of a dataset that already has a quota does not | |
1615 | override the ancestor's quota, but rather imposes an additional limit. | |
1616 | .Pp | |
1617 | Quotas cannot be set on volumes, as the | |
1618 | .Sy volsize | |
1619 | property acts as an implicit quota. | |
1620 | .It Sy snapshot_limit Ns = Ns Em count Ns | Ns Sy none | |
788eb90c | 1621 | Limits the number of snapshots that can be created on a dataset and its |
44f09cdc BB |
1622 | descendents. |
1623 | Setting a | |
1624 | .Sy snapshot_limit | |
1625 | on a descendent of a dataset that already has a | |
1626 | .Sy snapshot_limit | |
1627 | does not override the ancestor's | |
1628 | .Sy snapshot_limit , | |
1629 | but rather imposes an additional limit. | |
1630 | The limit is not enforced if the user is allowed to change the limit. | |
1631 | For example, this means that recursive snapshots taken from the global zone are | |
1632 | counted against each delegated dataset within a zone. | |
1633 | This feature must be enabled to be used | |
1634 | .Po see | |
1635 | .Xr zpool-features 5 | |
1636 | .Pc . | |
1637 | .It Sy userquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none | |
1638 | Limits the amount of space consumed by the specified user. | |
1639 | User space consumption is identified by the | |
1640 | .Sy userspace@ Ns Em user | |
1641 | property. | |
1642 | .Pp | |
1643 | Enforcement of user quotas may be delayed by several seconds. | |
1644 | This delay means that a user might exceed their quota before the system notices | |
1645 | that they are over quota and begins to refuse additional writes with the | |
1646 | .Er EDQUOT | |
1647 | error message. | |
1648 | See the | |
1649 | .Nm zfs Cm userspace | |
1650 | subcommand for more information. | |
1651 | .Pp | |
1652 | Unprivileged users can only access their own groups' space usage. | |
1653 | The root user, or a user who has been granted the | |
1654 | .Sy userquota | |
1655 | privilege with | |
1656 | .Nm zfs Cm allow , | |
1657 | can get and set everyone's quota. | |
1658 | .Pp | |
1659 | This property is not available on volumes, on file systems before version 4, or | |
1660 | on pools before version 15. | |
1661 | The | |
1662 | .Sy userquota@ Ns Em ... | |
1663 | properties are not displayed by | |
1664 | .Nm zfs Cm get Sy all . | |
1665 | The user's name must be appended after the | |
1666 | .Sy @ | |
1667 | symbol, using one of the following forms: | |
1668 | .Bl -bullet | |
1669 | .It | |
1670 | .Em POSIX name | |
1671 | .Po for example, | |
1672 | .Sy joe | |
1673 | .Pc | |
1674 | .It | |
1675 | .Em POSIX numeric ID | |
1676 | .Po for example, | |
1677 | .Sy 789 | |
1678 | .Pc | |
1679 | .It | |
1680 | .Em SID name | |
1681 | .Po for example, | |
1682 | .Sy joe.smith@mydomain | |
1683 | .Pc | |
1684 | .It | |
1685 | .Em SID numeric ID | |
1686 | .Po for example, | |
1687 | .Sy S-1-123-456-789 | |
1688 | .Pc | |
1689 | .El | |
1690 | .Pp | |
6a107f41 | 1691 | Files created on Linux always have POSIX owners. |
44f09cdc BB |
1692 | .It Sy userobjquota@ Ns Em user Ns = Ns Em size Ns | Ns Sy none |
1693 | The | |
1694 | .Sy userobjquota | |
1695 | is similar to | |
1696 | .Sy userquota | |
1697 | but it limits the number of objects a user can create. Please refer to | |
1698 | .Sy userobjused | |
1699 | for more information about how objects are counted. | |
1700 | .It Sy groupquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none | |
1701 | Limits the amount of space consumed by the specified group. | |
1702 | Group space consumption is identified by the | |
1703 | .Sy groupused@ Ns Em group | |
1704 | property. | |
1705 | .Pp | |
1706 | Unprivileged users can access only their own groups' space usage. | |
1707 | The root user, or a user who has been granted the | |
1708 | .Sy groupquota | |
1709 | privilege with | |
1710 | .Nm zfs Cm allow , | |
1711 | can get and set all groups' quotas. | |
1712 | .It Sy groupobjquota@ Ns Em group Ns = Ns Em size Ns | Ns Sy none | |
1713 | The | |
1714 | .Sy groupobjquota | |
1715 | is similar to | |
1716 | .Sy groupquota | |
1717 | but it limits number of objects a group can consume. Please refer to | |
1718 | .Sy userobjused | |
1719 | for more information about how objects are counted. | |
9c5167d1 NF |
1720 | .It Sy projectquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none |
1721 | Limits the amount of space consumed by the specified project. Project | |
1722 | space consumption is identified by the | |
1723 | .Sy projectused@ Ns Em project | |
1724 | property. Please refer to | |
1725 | .Sy projectused | |
1726 | for more information about how project is identified and set/changed. | |
1727 | .Pp | |
1728 | The root user, or a user who has been granted the | |
1729 | .Sy projectquota | |
1730 | privilege with | |
1731 | .Nm zfs allow , | |
1732 | can access all projects' quota. | |
1733 | .It Sy projectobjquota@ Ns Em project Ns = Ns Em size Ns | Ns Sy none | |
1734 | The | |
1735 | .Sy projectobjquota | |
1736 | is similar to | |
1737 | .Sy projectquota | |
1738 | but it limits number of objects a project can consume. Please refer to | |
1739 | .Sy userobjused | |
1740 | for more information about how objects are counted. | |
44f09cdc BB |
1741 | .It Sy readonly Ns = Ns Sy on Ns | Ns Sy off |
1742 | Controls whether this dataset can be modified. | |
1743 | The default value is | |
1744 | .Sy off . | |
1745 | The values | |
1746 | .Sy on | |
1747 | and | |
1748 | .Sy off | |
1749 | are equivalent to the | |
1750 | .Sy ro | |
1751 | and | |
1752 | .Sy rw | |
1753 | mount options. | |
1754 | .Pp | |
1755 | This property can also be referred to by its shortened column name, | |
1756 | .Sy rdonly . | |
1757 | .It Sy recordsize Ns = Ns Em size | |
1758 | Specifies a suggested block size for files in the file system. | |
1759 | This property is designed solely for use with database workloads that access | |
1760 | files in fixed-size records. | |
1761 | ZFS automatically tunes block sizes according to internal algorithms optimized | |
1762 | for typical access patterns. | |
1763 | .Pp | |
1764 | For databases that create very large files but access them in small random | |
1765 | chunks, these algorithms may be suboptimal. | |
1766 | Specifying a | |
1767 | .Sy recordsize | |
1768 | greater than or equal to the record size of the database can result in | |
1769 | significant performance gains. | |
1770 | Use of this property for general purpose file systems is strongly discouraged, | |
1771 | and may adversely affect performance. | |
1772 | .Pp | |
1773 | The size specified must be a power of two greater than or equal to 512 and less | |
1774 | than or equal to 128 Kbytes. | |
1775 | If the | |
1776 | .Sy large_blocks | |
1777 | feature is enabled on the pool, the size may be up to 1 Mbyte. | |
1778 | See | |
1779 | .Xr zpool-features 5 | |
1780 | for details on ZFS feature flags. | |
1781 | .Pp | |
1782 | Changing the file system's | |
1783 | .Sy recordsize | |
1784 | affects only files created afterward; existing files are unaffected. | |
1785 | .Pp | |
1786 | This property can also be referred to by its shortened column name, | |
1787 | .Sy recsize . | |
1788 | .It Sy redundant_metadata Ns = Ns Sy all Ns | Ns Sy most | |
1789 | Controls what types of metadata are stored redundantly. | |
1790 | ZFS stores an extra copy of metadata, so that if a single block is corrupted, | |
1791 | the amount of user data lost is limited. | |
1792 | This extra copy is in addition to any redundancy provided at the pool level | |
1793 | .Pq e.g. by mirroring or RAID-Z , | |
1794 | and is in addition to an extra copy specified by the | |
1795 | .Sy copies | |
1796 | property | |
1797 | .Pq up to a total of 3 copies . | |
1798 | For example if the pool is mirrored, | |
1799 | .Sy copies Ns = Ns 2 , | |
1800 | and | |
1801 | .Sy redundant_metadata Ns = Ns Sy most , | |
1802 | then ZFS stores 6 copies of most metadata, and 4 copies of data and some | |
faf0f58c | 1803 | metadata. |
44f09cdc BB |
1804 | .Pp |
1805 | When set to | |
1806 | .Sy all , | |
1807 | ZFS stores an extra copy of all metadata. | |
1808 | If a single on-disk block is corrupt, at worst a single block of user data | |
1809 | .Po which is | |
1810 | .Sy recordsize | |
1811 | bytes long | |
1812 | .Pc | |
1813 | can be lost. | |
1814 | .Pp | |
1815 | When set to | |
1816 | .Sy most , | |
1817 | ZFS stores an extra copy of most types of metadata. | |
1818 | This can improve performance of random writes, because less metadata must be | |
1819 | written. | |
1820 | In practice, at worst about 100 blocks | |
1821 | .Po of | |
1822 | .Sy recordsize | |
1823 | bytes each | |
1824 | .Pc | |
1825 | of user data can be lost if a single on-disk block is corrupt. | |
1826 | The exact behavior of which metadata blocks are stored redundantly may change in | |
1827 | future releases. | |
1828 | .Pp | |
1829 | The default value is | |
1830 | .Sy all . | |
1831 | .It Sy refquota Ns = Ns Em size Ns | Ns Sy none | |
1832 | Limits the amount of space a dataset can consume. | |
1833 | This property enforces a hard limit on the amount of space used. | |
1834 | This hard limit does not include space used by descendents, including file | |
1835 | systems and snapshots. | |
d22f3a82 | 1836 | .It Sy refreservation Ns = Ns Em size Ns | Ns Sy none Ns | Ns Sy auto |
44f09cdc BB |
1837 | The minimum amount of space guaranteed to a dataset, not including its |
1838 | descendents. | |
1839 | When the amount of space used is below this value, the dataset is treated as if | |
1840 | it were taking up the amount of space specified by | |
1841 | .Sy refreservation . | |
1842 | The | |
1843 | .Sy refreservation | |
1844 | reservation is accounted for in the parent datasets' space used, and counts | |
1845 | against the parent datasets' quotas and reservations. | |
1846 | .Pp | |
1847 | If | |
1848 | .Sy refreservation | |
1849 | is set, a snapshot is only allowed if there is enough free pool space outside of | |
1850 | this reservation to accommodate the current number of | |
1851 | .Qq referenced | |
1852 | bytes in the dataset. | |
1853 | .Pp | |
d22f3a82 MG |
1854 | If |
1855 | .Sy refreservation | |
1856 | is set to | |
1857 | .Sy auto , | |
1858 | a volume is thick provisioned | |
1859 | .Po or | |
1860 | .Qq not sparse | |
1861 | .Pc . | |
1862 | .Sy refreservation Ns = Ns Sy auto | |
1863 | is only supported on volumes. | |
1864 | See | |
1865 | .Sy volsize | |
1866 | in the | |
1867 | .Sx Native Properties | |
1868 | section for more information about sparse volumes. | |
1869 | .Pp | |
44f09cdc BB |
1870 | This property can also be referred to by its shortened column name, |
1871 | .Sy refreserv . | |
1872 | .It Sy relatime Ns = Ns Sy on Ns | Ns Sy off | |
1873 | Controls the manner in which the access time is updated when | |
1874 | .Sy atime=on | |
1875 | is set. Turning this property on causes the access time to be updated relative | |
1876 | to the modify or change time. Access time is only updated if the previous | |
1877 | access time was earlier than the current modify or change time or if the | |
1878 | existing access time hasn't been updated within the past 24 hours. The default | |
1879 | value is | |
1880 | .Sy off . | |
1881 | The values | |
1882 | .Sy on | |
1883 | and | |
1884 | .Sy off | |
1885 | are equivalent to the | |
1886 | .Sy relatime | |
1887 | and | |
1888 | .Sy norelatime | |
1889 | mount options. | |
1890 | .It Sy reservation Ns = Ns Em size Ns | Ns Sy none | |
1891 | The minimum amount of space guaranteed to a dataset and its descendants. | |
1892 | When the amount of space used is below this value, the dataset is treated as if | |
1893 | it were taking up the amount of space specified by its reservation. | |
1894 | Reservations are accounted for in the parent datasets' space used, and count | |
1895 | against the parent datasets' quotas and reservations. | |
1896 | .Pp | |
1897 | This property can also be referred to by its shortened column name, | |
1898 | .Sy reserv . | |
1899 | .It Sy secondarycache Ns = Ns Sy all Ns | Ns Sy none Ns | Ns Sy metadata | |
1900 | Controls what is cached in the secondary cache | |
1901 | .Pq L2ARC . | |
1902 | If this property is set to | |
1903 | .Sy all , | |
1904 | then both user data and metadata is cached. | |
1905 | If this property is set to | |
1906 | .Sy none , | |
1907 | then neither user data nor metadata is cached. | |
1908 | If this property is set to | |
1909 | .Sy metadata , | |
1910 | then only metadata is cached. | |
1911 | The default value is | |
1912 | .Sy all . | |
1913 | .It Sy setuid Ns = Ns Sy on Ns | Ns Sy off | |
1914 | Controls whether the setuid bit is respected for the file system. | |
1915 | The default value is | |
1916 | .Sy on . | |
1917 | The values | |
1918 | .Sy on | |
1919 | and | |
1920 | .Sy off | |
1921 | are equivalent to the | |
1922 | .Sy suid | |
1923 | and | |
1924 | .Sy nosuid | |
1925 | mount options. | |
1926 | .It Sy sharesmb Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts | |
1927 | Controls whether the file system is shared by using | |
1928 | .Sy Samba USERSHARES | |
1929 | and what options are to be used. Otherwise, the file system is automatically | |
1930 | shared and unshared with the | |
1931 | .Nm zfs Cm share | |
1932 | and | |
1933 | .Nm zfs Cm unshare | |
1934 | commands. If the property is set to on, the | |
1935 | .Xr net 8 | |
1936 | command is invoked to create a | |
1937 | .Sy USERSHARE . | |
1938 | .Pp | |
1939 | Because SMB shares requires a resource name, a unique resource name is | |
1940 | constructed from the dataset name. The constructed name is a copy of the | |
1941 | dataset name except that the characters in the dataset name, which would be | |
1942 | invalid in the resource name, are replaced with underscore (_) characters. | |
1943 | Linux does not currently support additional options which might be available | |
1944 | on Solaris. | |
1945 | .Pp | |
1946 | If the | |
1947 | .Sy sharesmb | |
1948 | property is set to | |
1949 | .Sy off , | |
1950 | the file systems are unshared. | |
1951 | .Pp | |
1952 | The share is created with the ACL (Access Control List) "Everyone:F" ("F" | |
1953 | stands for "full permissions", ie. read and write permissions) and no guest | |
1954 | access (which means Samba must be able to authenticate a real user, system | |
1955 | passwd/shadow, LDAP or smbpasswd based) by default. This means that any | |
1956 | additional access control (disallow specific user specific access etc) must | |
1957 | be done on the underlying file system. | |
1958 | .It Sy sharenfs Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Em opts | |
1959 | Controls whether the file system is shared via NFS, and what options are to be | |
1960 | used. | |
1961 | A file system with a | |
1962 | .Sy sharenfs | |
1963 | property of | |
1964 | .Sy off | |
1965 | is managed with the | |
1966 | .Xr exportfs 8 | |
1967 | command and entries in the | |
1968 | .Em /etc/exports | |
1969 | file. | |
1970 | Otherwise, the file system is automatically shared and unshared with the | |
1971 | .Nm zfs Cm share | |
1972 | and | |
1973 | .Nm zfs Cm unshare | |
1974 | commands. | |
1975 | If the property is set to | |
1976 | .Sy on , | |
1977 | the dataset is shared using the default options: | |
1978 | .Pp | |
1979 | .Em sec=sys,rw,crossmnt,no_subtree_check,no_root_squash | |
1980 | .Pp | |
1981 | See | |
1982 | .Xr exports 5 | |
1983 | for the meaning of the default options. Otherwise, the | |
1984 | .Xr exportfs 8 | |
1985 | command is invoked with options equivalent to the contents of this property. | |
1986 | .Pp | |
1987 | When the | |
1988 | .Sy sharenfs | |
1989 | property is changed for a dataset, the dataset and any children inheriting the | |
1990 | property are re-shared with the new options, only if the property was previously | |
1991 | .Sy off , | |
1992 | or if they were shared before the property was changed. | |
1993 | If the new property is | |
1994 | .Sy off , | |
1995 | the file systems are unshared. | |
1996 | .It Sy logbias Ns = Ns Sy latency Ns | Ns Sy throughput | |
1997 | Provide a hint to ZFS about handling of synchronous requests in this dataset. | |
1998 | If | |
1999 | .Sy logbias | |
2000 | is set to | |
2001 | .Sy latency | |
2002 | .Pq the default , | |
2003 | ZFS will use pool log devices | |
2004 | .Pq if configured | |
2005 | to handle the requests at low latency. | |
2006 | If | |
2007 | .Sy logbias | |
2008 | is set to | |
2009 | .Sy throughput , | |
2010 | ZFS will not use configured pool log devices. | |
2011 | ZFS will instead optimize synchronous operations for global pool throughput and | |
2012 | efficient use of resources. | |
2013 | .It Sy snapdev Ns = Ns Sy hidden Ns | Ns Sy visible | |
2014 | Controls whether the volume snapshot devices under | |
2015 | .Em /dev/zvol/<pool> | |
2016 | are hidden or visible. The default value is | |
2017 | .Sy hidden . | |
2018 | .It Sy snapdir Ns = Ns Sy hidden Ns | Ns Sy visible | |
2019 | Controls whether the | |
2020 | .Pa .zfs | |
2021 | directory is hidden or visible in the root of the file system as discussed in | |
2022 | the | |
2023 | .Sx Snapshots | |
2024 | section. | |
2025 | The default value is | |
2026 | .Sy hidden . | |
2027 | .It Sy sync Ns = Ns Sy standard Ns | Ns Sy always Ns | Ns Sy disabled | |
2028 | Controls the behavior of synchronous requests | |
2029 | .Pq e.g. fsync, O_DSYNC . | |
2030 | .Sy standard | |
2031 | is the | |
2032 | .Tn POSIX | |
2033 | specified behavior of ensuring all synchronous requests are written to stable | |
2034 | storage and all devices are flushed to ensure data is not cached by device | |
2035 | controllers | |
2036 | .Pq this is the default . | |
2037 | .Sy always | |
330d06f9 | 2038 | causes every file system transaction to be written and flushed before its |
44f09cdc BB |
2039 | system call returns. |
2040 | This has a large performance penalty. | |
2041 | .Sy disabled | |
2042 | disables synchronous requests. | |
2043 | File system transactions are only committed to stable storage periodically. | |
2044 | This option will give the highest performance. | |
330d06f9 | 2045 | However, it is very dangerous as ZFS would be ignoring the synchronous |
44f09cdc BB |
2046 | transaction demands of applications such as databases or NFS. |
2047 | Administrators should only use this option when the risks are understood. | |
2048 | .It Sy version Ns = Ns Em N Ns | Ns Sy current | |
2049 | The on-disk version of this file system, which is independent of the pool | |
2050 | version. | |
2051 | This property can only be set to later supported versions. | |
2052 | See the | |
2053 | .Nm zfs Cm upgrade | |
2054 | command. | |
2055 | .It Sy volsize Ns = Ns Em size | |
2056 | For volumes, specifies the logical size of the volume. | |
2057 | By default, creating a volume establishes a reservation of equal size. | |
2058 | For storage pools with a version number of 9 or higher, a | |
2059 | .Sy refreservation | |
2060 | is set instead. | |
2061 | Any changes to | |
2062 | .Sy volsize | |
2063 | are reflected in an equivalent change to the reservation | |
2064 | .Po or | |
2065 | .Sy refreservation | |
2066 | .Pc . | |
2067 | The | |
2068 | .Sy volsize | |
2069 | can only be set to a multiple of | |
2070 | .Sy volblocksize , | |
2071 | and cannot be zero. | |
2072 | .Pp | |
2073 | The reservation is kept equal to the volume's logical size to prevent unexpected | |
2074 | behavior for consumers. | |
2075 | Without the reservation, the volume could run out of space, resulting in | |
2076 | undefined behavior or data corruption, depending on how the volume is used. | |
2077 | These effects can also occur when the volume size is changed while it is in use | |
2078 | .Pq particularly when shrinking the size . | |
2079 | Extreme care should be used when adjusting the volume size. | |
2080 | .Pp | |
2081 | Though not recommended, a | |
2082 | .Qq sparse volume | |
2083 | .Po also known as | |
d22f3a82 | 2084 | .Qq thin provisioned |
44f09cdc BB |
2085 | .Pc |
2086 | can be created by specifying the | |
2087 | .Fl s | |
2088 | option to the | |
2089 | .Nm zfs Cm create Fl V | |
d22f3a82 MG |
2090 | command, or by changing the value of the |
2091 | .Sy refreservation | |
2092 | property | |
2093 | .Po or | |
2094 | .Sy reservation | |
2095 | property on pool version 8 or earlier | |
2096 | .Pc | |
2097 | after the volume has been created. | |
44f09cdc BB |
2098 | A |
2099 | .Qq sparse volume | |
d22f3a82 MG |
2100 | is a volume where the value of |
2101 | .Sy refreservation | |
2102 | is less than the size of the volume plus the space required to store its | |
2103 | metadata. | |
44f09cdc BB |
2104 | Consequently, writes to a sparse volume can fail with |
2105 | .Er ENOSPC | |
2106 | when the pool is low on space. | |
2107 | For a sparse volume, changes to | |
2108 | .Sy volsize | |
d22f3a82 MG |
2109 | are not reflected in the |
2110 | .Sy refreservation. | |
2111 | A volume that is not sparse is said to be | |
2112 | .Qq thick provisioned . | |
2113 | A sparse volume can become thick provisioned by setting | |
2114 | .Sy refreservation | |
2115 | to | |
2116 | .Sy auto . | |
cf8738d8 | 2117 | .It Sy volmode Ns = Ns Cm default | full | geom | dev | none |
2118 | This property specifies how volumes should be exposed to the OS. | |
2119 | Setting it to | |
2120 | .Sy full | |
2121 | exposes volumes as fully fledged block devices, providing maximal | |
2122 | functionality. The value | |
2123 | .Sy geom | |
2124 | is just an alias for | |
2125 | .Sy full | |
2126 | and is kept for compatibility. | |
2127 | Setting it to | |
2128 | .Sy dev | |
2129 | hides its partitions. | |
2130 | Volumes with property set to | |
2131 | .Sy none | |
2132 | are not exposed outside ZFS, but can be snapshoted, cloned, replicated, etc, | |
2133 | that can be suitable for backup purposes. | |
2134 | Value | |
2135 | .Sy default | |
2136 | means that volumes exposition is controlled by system-wide tunable | |
2137 | .Va zvol_volmode , | |
2138 | where | |
2139 | .Sy full , | |
2140 | .Sy dev | |
2141 | and | |
2142 | .Sy none | |
2143 | are encoded as 1, 2 and 3 respectively. | |
2144 | The default values is | |
2145 | .Sy full . | |
44f09cdc BB |
2146 | .It Sy vscan Ns = Ns Sy on Ns | Ns Sy off |
2147 | Controls whether regular files should be scanned for viruses when a file is | |
2148 | opened and closed. | |
2149 | In addition to enabling this property, the virus scan service must also be | |
2150 | enabled for virus scanning to occur. | |
2151 | The default value is | |
2152 | .Sy off . | |
6a107f41 | 2153 | This property is not used on Linux. |
44f09cdc BB |
2154 | .It Sy xattr Ns = Ns Sy on Ns | Ns Sy off Ns | Ns Sy sa |
2155 | Controls whether extended attributes are enabled for this file system. Two | |
7c2448a3 BB |
2156 | styles of extended attributes are supported either directory based or system |
2157 | attribute based. | |
44f09cdc BB |
2158 | .Pp |
2159 | The default value of | |
2160 | .Sy on | |
2161 | enables directory based extended attributes. This style of extended attribute | |
2162 | imposes no practical limit on either the size or number of attributes which | |
2163 | can be set on a file. Although under Linux the | |
2164 | .Xr getxattr 2 | |
2165 | and | |
2166 | .Xr setxattr 2 | |
2167 | system calls limit the maximum size to 64K. This is the most compatible | |
2168 | style of extended attribute and is supported by all OpenZFS implementations. | |
2169 | .Pp | |
2170 | System attribute based xattrs can be enabled by setting the value to | |
2171 | .Sy sa . | |
2172 | The key advantage of this type of xattr is improved performance. Storing | |
2173 | extended attributes as system attributes significantly decreases the amount of | |
2174 | disk IO required. Up to 64K of data may be stored per-file in the space | |
2175 | reserved for system attributes. If there is not enough space available for | |
2176 | an extended attribute then it will be automatically written as a directory | |
2177 | based xattr. System attribute based extended attributes are not accessible | |
2178 | on platforms which do not support the | |
2179 | .Sy xattr=sa | |
2180 | feature. | |
2181 | .Pp | |
7c2448a3 | 2182 | The use of system attribute based xattrs is strongly encouraged for users of |
06f3fc2a | 2183 | SELinux or POSIX ACLs. Both of these features heavily rely of extended |
44f09cdc BB |
2184 | attributes and benefit significantly from the reduced access time. |
2185 | .Pp | |
2186 | The values | |
2187 | .Sy on | |
2188 | and | |
2189 | .Sy off | |
2190 | are equivalent to the | |
2191 | .Sy xattr | |
2192 | and | |
2193 | .Sy noxattr | |
2194 | mount options. | |
2195 | .It Sy zoned Ns = Ns Sy on Ns | Ns Sy off | |
2196 | Controls whether the dataset is managed from a non-global zone. Zones are a | |
2197 | Solaris feature and are not relevant on Linux. The default value is | |
2198 | .Sy off . | |
2199 | .El | |
2200 | .Pp | |
2201 | The following three properties cannot be changed after the file system is | |
2202 | created, and therefore, should be set when the file system is created. | |
2203 | If the properties are not set with the | |
2204 | .Nm zfs Cm create | |
2205 | or | |
2206 | .Nm zpool Cm create | |
2207 | commands, these properties are inherited from the parent dataset. | |
2208 | If the parent dataset lacks these properties due to having been created prior to | |
2209 | these features being supported, the new file system will have the default values | |
2210 | for these properties. | |
2211 | .Bl -tag -width "" | |
2212 | .It Xo | |
2213 | .Sy casesensitivity Ns = Ns Sy sensitive Ns | Ns | |
2214 | .Sy insensitive Ns | Ns Sy mixed | |
2215 | .Xc | |
2216 | Indicates whether the file name matching algorithm used by the file system | |
2217 | should be case-sensitive, case-insensitive, or allow a combination of both | |
2218 | styles of matching. | |
2219 | The default value for the | |
2220 | .Sy casesensitivity | |
2221 | property is | |
2222 | .Sy sensitive . | |
2223 | Traditionally, | |
2224 | .Ux | |
2225 | and | |
2226 | .Tn POSIX | |
2227 | file systems have case-sensitive file names. | |
2228 | .Pp | |
2229 | The | |
2230 | .Sy mixed | |
2231 | value for the | |
2232 | .Sy casesensitivity | |
2233 | property indicates that the file system can support requests for both | |
2234 | case-sensitive and case-insensitive matching behavior. | |
2235 | Currently, case-insensitive matching behavior on a file system that supports | |
2236 | mixed behavior is limited to the SMB server product. | |
2237 | For more information about the | |
2238 | .Sy mixed | |
2239 | value behavior, see the "ZFS Administration Guide". | |
2240 | .It Xo | |
2241 | .Sy normalization Ns = Ns Sy none Ns | Ns Sy formC Ns | Ns | |
2242 | .Sy formD Ns | Ns Sy formKC Ns | Ns Sy formKD | |
2243 | .Xc | |
2244 | Indicates whether the file system should perform a | |
2245 | .Sy unicode | |
2246 | normalization of file names whenever two file names are compared, and which | |
2247 | normalization algorithm should be used. | |
2248 | File names are always stored unmodified, names are normalized as part of any | |
2249 | comparison process. | |
2250 | If this property is set to a legal value other than | |
2251 | .Sy none , | |
2252 | and the | |
2253 | .Sy utf8only | |
2254 | property was left unspecified, the | |
2255 | .Sy utf8only | |
2256 | property is automatically set to | |
2257 | .Sy on . | |
2258 | The default value of the | |
2259 | .Sy normalization | |
2260 | property is | |
2261 | .Sy none . | |
8fd888ba | 2262 | This property cannot be changed after the file system is created. |
44f09cdc BB |
2263 | .It Sy utf8only Ns = Ns Sy on Ns | Ns Sy off |
2264 | Indicates whether the file system should reject file names that include | |
2265 | characters that are not present in the | |
2266 | .Sy UTF-8 | |
2267 | character code set. | |
2268 | If this property is explicitly set to | |
2269 | .Sy off , | |
2270 | the normalization property must either not be explicitly set or be set to | |
2271 | .Sy none . | |
2272 | The default value for the | |
2273 | .Sy utf8only | |
2274 | property is | |
2275 | .Sy off . | |
8fd888ba | 2276 | This property cannot be changed after the file system is created. |
44f09cdc BB |
2277 | .El |
2278 | .Pp | |
2279 | The | |
2280 | .Sy casesensitivity , | |
2281 | .Sy normalization , | |
2282 | and | |
2283 | .Sy utf8only | |
2284 | properties are also new permissions that can be assigned to non-privileged users | |
2285 | by using the ZFS delegated administration feature. | |
2286 | .Ss "Temporary Mount Point Properties" | |
2287 | When a file system is mounted, either through | |
2288 | .Xr mount 8 | |
2289 | for legacy mounts or the | |
2290 | .Nm zfs Cm mount | |
2291 | command for normal file systems, its mount options are set according to its | |
2292 | properties. | |
2293 | The correlation between properties and mount options is as follows: | |
2294 | .Bd -literal | |
058ac9ba | 2295 | PROPERTY MOUNT OPTION |
44f09cdc BB |
2296 | atime atime/noatime |
2297 | canmount auto/noauto | |
2298 | devices dev/nodev | |
2299 | exec exec/noexec | |
2300 | readonly ro/rw | |
2301 | relatime relatime/norelatime | |
2302 | setuid suid/nosuid | |
2303 | xattr xattr/noxattr | |
2304 | .Ed | |
2305 | .Pp | |
2306 | In addition, these options can be set on a per-mount basis using the | |
2307 | .Fl o | |
2308 | option, without affecting the property that is stored on disk. | |
2309 | The values specified on the command line override the values stored in the | |
2310 | dataset. | |
2311 | The | |
2312 | .Sy nosuid | |
2313 | option is an alias for | |
d7323e79 | 2314 | .Sy nodevices Ns \&, Ns Sy nosetuid . |
44f09cdc BB |
2315 | These properties are reported as |
2316 | .Qq temporary | |
2317 | by the | |
2318 | .Nm zfs Cm get | |
2319 | command. | |
2320 | If the properties are changed while the dataset is mounted, the new setting | |
2321 | overrides any temporary settings. | |
2322 | .Ss "User Properties" | |
2323 | In addition to the standard native properties, ZFS supports arbitrary user | |
2324 | properties. | |
2325 | User properties have no effect on ZFS behavior, but applications or | |
2326 | administrators can use them to annotate datasets | |
2327 | .Pq file systems, volumes, and snapshots . | |
2328 | .Pp | |
2329 | User property names must contain a colon | |
2330 | .Pq Qq Sy \&: | |
2331 | character to distinguish them from native properties. | |
2332 | They may contain lowercase letters, numbers, and the following punctuation | |
2333 | characters: colon | |
2334 | .Pq Qq Sy \&: , | |
2335 | dash | |
2336 | .Pq Qq Sy - , | |
2337 | period | |
2338 | .Pq Qq Sy \&. , | |
2339 | and underscore | |
2340 | .Pq Qq Sy _ . | |
2341 | The expected convention is that the property name is divided into two portions | |
2342 | such as | |
d7323e79 | 2343 | .Em module Ns \&: Ns Em property , |
44f09cdc BB |
2344 | but this namespace is not enforced by ZFS. |
2345 | User property names can be at most 256 characters, and cannot begin with a dash | |
2346 | .Pq Qq Sy - . | |
2347 | .Pp | |
2348 | When making programmatic use of user properties, it is strongly suggested to use | |
2349 | a reversed | |
2350 | .Sy DNS | |
2351 | domain name for the | |
2352 | .Em module | |
2353 | component of property names to reduce the chance that two | |
2354 | independently-developed packages use the same property name for different | |
2355 | purposes. | |
2356 | .Pp | |
2357 | The values of user properties are arbitrary strings, are always inherited, and | |
2358 | are never validated. | |
2359 | All of the commands that operate on properties | |
2360 | .Po Nm zfs Cm list , | |
2361 | .Nm zfs Cm get , | |
2362 | .Nm zfs Cm set , | |
2363 | and so forth | |
2364 | .Pc | |
2365 | can be used to manipulate both native properties and user properties. | |
2366 | Use the | |
2367 | .Nm zfs Cm inherit | |
2368 | command to clear a user property. | |
2369 | If the property is not defined in any parent dataset, it is removed entirely. | |
2370 | Property values are limited to 8192 bytes. | |
2371 | .Ss ZFS Volumes as Swap | |
2372 | ZFS volumes may be used as swap devices. After creating the volume with the | |
2373 | .Nm zfs Cm create Fl V | |
2374 | command set up and enable the swap area using the | |
2375 | .Xr mkswap 8 | |
2376 | and | |
2377 | .Xr swapon 8 | |
2378 | commands. Do not swap to a file on a ZFS file system. A ZFS swap file | |
2379 | configuration is not supported. | |
b5256303 TC |
2380 | .Ss Encryption |
2381 | Enabling the | |
2382 | .Sy encryption | |
2b127afb RL |
2383 | feature allows for the creation of encrypted filesystems and volumes. ZFS |
2384 | will encrypt file and zvol data, file attributes, ACLs, permission bits, | |
2385 | directory listings, FUID mappings, and | |
2386 | .Sy userused | |
2387 | / | |
2388 | .Sy groupused | |
2389 | data. ZFS will not encrypt metadata related to the pool structure, including | |
2390 | dataset and snapshot names, dataset hierarchy, properties, file size, file | |
2391 | holes, and deduplication tables. | |
2392 | .Pp | |
2393 | Key rotation is managed by ZFS. Changing the user's key (e.g. a passphrase) | |
2394 | does not require re-encrypting the entire dataset. Datasets can be scrubbed, | |
2395 | resilvered, renamed, and deleted without the encryption keys being loaded (see the | |
b5256303 TC |
2396 | .Nm zfs Cm load-key |
2397 | subcommand for more info on key loading). | |
2398 | .Pp | |
2399 | Creating an encrypted dataset requires specifying the | |
2400 | .Sy encryption | |
2401 | and | |
2402 | .Sy keyformat | |
2403 | properties at creation time, along with an optional | |
90cdf283 | 2404 | .Sy keylocation |
b5256303 TC |
2405 | and |
2406 | .Sy pbkdf2iters . | |
2407 | After entering an encryption key, the | |
2408 | created dataset will become an encryption root. Any descendant datasets will | |
4807c0ba TC |
2409 | inherit their encryption key from the encryption root by default, meaning that |
2410 | loading, unloading, or changing the key for the encryption root will implicitly | |
2411 | do the same for all inheriting datasets. If this inheritance is not desired, | |
2412 | simply supply a | |
b5256303 TC |
2413 | .Sy keyformat |
2414 | when creating the child dataset or use | |
2415 | .Nm zfs Cm change-key | |
4807c0ba TC |
2416 | to break an existing relationship, creating a new encryption root on the child. |
2417 | Note that the child's | |
2418 | .Sy keyformat | |
2419 | may match that of the parent while still creating a new encryption root, and | |
2420 | that changing the | |
2421 | .Sy encryption | |
2422 | property alone does not create a new encryption root; this would simply use a | |
2423 | different cipher suite with the same key as its encryption root. The one | |
2424 | exception is that clones will always use their origin's encryption key. | |
2425 | As a result of this exception, some encryption-related properties (namely | |
2426 | .Sy keystatus , | |
2427 | .Sy keyformat , | |
2428 | .Sy keylocation , | |
2429 | and | |
2430 | .Sy pbkdf2iters ) | |
2431 | do not inherit like other ZFS properties and instead use the value determined | |
2432 | by their encryption root. Encryption root inheritance can be tracked via the | |
2433 | read-only | |
b5256303 TC |
2434 | .Sy encryptionroot |
2435 | property. | |
2436 | .Pp | |
2b127afb | 2437 | Encryption changes the behavior of a few ZFS |
b5256303 TC |
2438 | operations. Encryption is applied after compression so compression ratios are |
2439 | preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data | |
2440 | the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from | |
2441 | the encryption suite, which provides additional protection against maliciously | |
2442 | altered data. Deduplication is still possible with encryption enabled but for | |
2443 | security, datasets will only dedup against themselves, their snapshots, and | |
2444 | their clones. | |
2445 | .Pp | |
2446 | There are a few limitations on encrypted datasets. Encrypted data cannot be | |
2447 | embedded via the | |
2448 | .Sy embedded_data | |
2449 | feature. Encrypted datasets may not have | |
2450 | .Sy copies Ns = Ns Em 3 | |
2451 | since the implementation stores some encryption metadata where the third copy | |
2452 | would normally be. Since compression is applied before encryption datasets may | |
2453 | be vulnerable to a CRIME-like attack if applications accessing the data allow | |
2454 | for it. Deduplication with encryption will leak information about which blocks | |
2455 | are equivalent in a dataset and will incur an extra CPU cost per block written. | |
44f09cdc BB |
2456 | .Sh SUBCOMMANDS |
2457 | All subcommands that modify state are logged persistently to the pool in their | |
2458 | original form. | |
2459 | .Bl -tag -width "" | |
2460 | .It Nm Fl ? | |
058ac9ba | 2461 | Displays a help message. |
44f09cdc BB |
2462 | .It Xo |
2463 | .Nm | |
50478c6d T |
2464 | .Fl V, -version |
2465 | .Xc | |
2466 | An alias for the | |
2467 | .Nm zfs Cm version | |
2468 | subcommand. | |
2469 | .It Xo | |
2470 | .Nm | |
44f09cdc BB |
2471 | .Cm create |
2472 | .Op Fl p | |
2473 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... | |
2474 | .Ar filesystem | |
2475 | .Xc | |
2476 | Creates a new ZFS file system. | |
2477 | The file system is automatically mounted according to the | |
2478 | .Sy mountpoint | |
2479 | property inherited from the parent. | |
2480 | .Bl -tag -width "-o" | |
2481 | .It Fl o Ar property Ns = Ns Ar value | |
2482 | Sets the specified property as if the command | |
2483 | .Nm zfs Cm set Ar property Ns = Ns Ar value | |
2484 | was invoked at the same time the dataset was created. | |
2485 | Any editable ZFS property can also be set at creation time. | |
2486 | Multiple | |
2487 | .Fl o | |
2488 | options can be specified. | |
2489 | An error results if the same property is specified in multiple | |
2490 | .Fl o | |
2491 | options. | |
2492 | .It Fl p | |
2493 | Creates all the non-existing parent datasets. | |
2494 | Datasets created in this manner are automatically mounted according to the | |
2495 | .Sy mountpoint | |
2496 | property inherited from their parent. | |
2497 | Any property specified on the command line using the | |
2498 | .Fl o | |
2499 | option is ignored. | |
2500 | If the target filesystem already exists, the operation completes successfully. | |
2501 | .El | |
2502 | .It Xo | |
2503 | .Nm | |
2504 | .Cm create | |
2505 | .Op Fl ps | |
2506 | .Op Fl b Ar blocksize | |
2507 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... | |
2508 | .Fl V Ar size Ar volume | |
2509 | .Xc | |
2510 | Creates a volume of the given size. | |
2511 | The volume is exported as a block device in | |
2512 | .Pa /dev/zvol/path , | |
2513 | where | |
2514 | .Em path | |
2515 | is the name of the volume in the ZFS namespace. | |
2516 | The size represents the logical size as exported by the device. | |
2517 | By default, a reservation of equal size is created. | |
2518 | .Pp | |
2519 | .Ar size | |
2520 | is automatically rounded up to the nearest 128 Kbytes to ensure that the volume | |
2521 | has an integral number of blocks regardless of | |
2522 | .Sy blocksize . | |
2523 | .Bl -tag -width "-b" | |
2524 | .It Fl b Ar blocksize | |
2525 | Equivalent to | |
2526 | .Fl o Sy volblocksize Ns = Ns Ar blocksize . | |
2527 | If this option is specified in conjunction with | |
2528 | .Fl o Sy volblocksize , | |
2529 | the resulting behavior is undefined. | |
2530 | .It Fl o Ar property Ns = Ns Ar value | |
2531 | Sets the specified property as if the | |
2532 | .Nm zfs Cm set Ar property Ns = Ns Ar value | |
2533 | command was invoked at the same time the dataset was created. | |
2534 | Any editable ZFS property can also be set at creation time. | |
2535 | Multiple | |
2536 | .Fl o | |
2537 | options can be specified. | |
2538 | An error results if the same property is specified in multiple | |
2539 | .Fl o | |
2540 | options. | |
2541 | .It Fl p | |
2542 | Creates all the non-existing parent datasets. | |
2543 | Datasets created in this manner are automatically mounted according to the | |
2544 | .Sy mountpoint | |
2545 | property inherited from their parent. | |
2546 | Any property specified on the command line using the | |
2547 | .Fl o | |
2548 | option is ignored. | |
2549 | If the target filesystem already exists, the operation completes successfully. | |
2550 | .It Fl s | |
2551 | Creates a sparse volume with no reservation. | |
2552 | See | |
2553 | .Sy volsize | |
2554 | in the | |
2555 | .Sx Native Properties | |
2556 | section for more information about sparse volumes. | |
2557 | .El | |
2558 | .It Xo | |
2559 | .Nm | |
2560 | .Cm destroy | |
2561 | .Op Fl Rfnprv | |
2562 | .Ar filesystem Ns | Ns Ar volume | |
2563 | .Xc | |
2564 | Destroys the given dataset. | |
2565 | By default, the command unshares any file systems that are currently shared, | |
2566 | unmounts any file systems that are currently mounted, and refuses to destroy a | |
2567 | dataset that has active dependents | |
2568 | .Pq children or clones . | |
2569 | .Bl -tag -width "-R" | |
2570 | .It Fl R | |
2571 | Recursively destroy all dependents, including cloned file systems outside the | |
2572 | target hierarchy. | |
2573 | .It Fl f | |
2574 | Force an unmount of any file systems using the | |
2575 | .Nm unmount Fl f | |
2576 | command. | |
2577 | This option has no effect on non-file systems or unmounted file systems. | |
2578 | .It Fl n | |
2579 | Do a dry-run | |
2580 | .Pq Qq No-op | |
2581 | deletion. | |
2582 | No data will be deleted. | |
2583 | This is useful in conjunction with the | |
2584 | .Fl v | |
2585 | or | |
2586 | .Fl p | |
2587 | flags to determine what data would be deleted. | |
2588 | .It Fl p | |
330d06f9 | 2589 | Print machine-parsable verbose information about the deleted data. |
44f09cdc BB |
2590 | .It Fl r |
2591 | Recursively destroy all children. | |
2592 | .It Fl v | |
330d06f9 | 2593 | Print verbose information about the deleted data. |
44f09cdc BB |
2594 | .El |
2595 | .Pp | |
2596 | Extreme care should be taken when applying either the | |
2597 | .Fl r | |
2598 | or the | |
2599 | .Fl R | |
2600 | options, as they can destroy large portions of a pool and cause unexpected | |
2601 | behavior for mounted file systems in use. | |
2602 | .It Xo | |
2603 | .Nm | |
2604 | .Cm destroy | |
2605 | .Op Fl Rdnprv | |
2606 | .Ar filesystem Ns | Ns Ar volume Ns @ Ns Ar snap Ns | |
2607 | .Oo % Ns Ar snap Ns Oo , Ns Ar snap Ns Oo % Ns Ar snap Oc Oc Oc Ns ... | |
2608 | .Xc | |
2609 | The given snapshots are destroyed immediately if and only if the | |
2610 | .Nm zfs Cm destroy | |
2611 | command without the | |
2612 | .Fl d | |
2613 | option would have destroyed it. | |
2614 | Such immediate destruction would occur, for example, if the snapshot had no | |
2615 | clones and the user-initiated reference count were zero. | |
2616 | .Pp | |
2617 | If a snapshot does not qualify for immediate destruction, it is marked for | |
2618 | deferred deletion. | |
2619 | In this state, it exists as a usable, visible snapshot until both of the | |
2620 | preconditions listed above are met, at which point it is destroyed. | |
2621 | .Pp | |
2622 | An inclusive range of snapshots may be specified by separating the first and | |
2623 | last snapshots with a percent sign. | |
330d06f9 MA |
2624 | The first and/or last snapshots may be left blank, in which case the |
2625 | filesystem's oldest or newest snapshot will be implied. | |
44f09cdc | 2626 | .Pp |
330d06f9 | 2627 | Multiple snapshots |
44f09cdc BB |
2628 | .Pq or ranges of snapshots |
2629 | of the same filesystem or volume may be specified in a comma-separated list of | |
2630 | snapshots. | |
2631 | Only the snapshot's short name | |
2632 | .Po the part after the | |
2633 | .Sy @ | |
2634 | .Pc | |
2635 | should be specified when using a range or comma-separated list to identify | |
2636 | multiple snapshots. | |
2637 | .Bl -tag -width "-R" | |
2638 | .It Fl R | |
13fe0198 | 2639 | Recursively destroy all clones of these snapshots, including the clones, |
44f09cdc BB |
2640 | snapshots, and children. |
2641 | If this flag is specified, the | |
2642 | .Fl d | |
2643 | flag will have no effect. | |
2644 | .It Fl d | |
83362e8e PZ |
2645 | Destroy immediately. If a snapshot cannot be destroyed now, mark it for |
2646 | deferred destruction. | |
44f09cdc BB |
2647 | .It Fl n |
2648 | Do a dry-run | |
2649 | .Pq Qq No-op | |
2650 | deletion. | |
2651 | No data will be deleted. | |
2652 | This is useful in conjunction with the | |
2653 | .Fl p | |
2654 | or | |
2655 | .Fl v | |
2656 | flags to determine what data would be deleted. | |
2657 | .It Fl p | |
330d06f9 | 2658 | Print machine-parsable verbose information about the deleted data. |
44f09cdc BB |
2659 | .It Fl r |
2660 | Destroy | |
2661 | .Pq or mark for deferred deletion | |
2662 | all snapshots with this name in descendent file systems. | |
2663 | .It Fl v | |
330d06f9 | 2664 | Print verbose information about the deleted data. |
44f09cdc BB |
2665 | .Pp |
2666 | Extreme care should be taken when applying either the | |
2667 | .Fl r | |
2668 | or the | |
2669 | .Fl R | |
330d06f9 MA |
2670 | options, as they can destroy large portions of a pool and cause unexpected |
2671 | behavior for mounted file systems in use. | |
44f09cdc BB |
2672 | .El |
2673 | .It Xo | |
2674 | .Nm | |
2675 | .Cm destroy | |
2676 | .Ar filesystem Ns | Ns Ar volume Ns # Ns Ar bookmark | |
2677 | .Xc | |
da536844 | 2678 | The given bookmark is destroyed. |
44f09cdc BB |
2679 | .It Xo |
2680 | .Nm | |
2681 | .Cm snapshot | |
2682 | .Op Fl r | |
63f88c12 | 2683 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... |
44f09cdc BB |
2684 | .Ar filesystem Ns @ Ns Ar snapname Ns | Ns Ar volume Ns @ Ns Ar snapname Ns ... |
2685 | .Xc | |
2686 | Creates snapshots with the given names. | |
2687 | All previous modifications by successful system calls to the file system are | |
2688 | part of the snapshots. | |
2689 | Snapshots are taken atomically, so that all snapshots correspond to the same | |
2690 | moment in time. | |
63f88c12 | 2691 | .Nm zfs Cm snap |
2692 | can be used as an alias for | |
2693 | .Nm zfs Cm snapshot. | |
44f09cdc BB |
2694 | See the |
2695 | .Sx Snapshots | |
2696 | section for details. | |
2697 | .Bl -tag -width "-o" | |
2698 | .It Fl o Ar property Ns = Ns Ar value | |
2699 | Sets the specified property; see | |
2700 | .Nm zfs Cm create | |
2701 | for details. | |
2702 | .It Fl r | |
2703 | Recursively create snapshots of all descendent datasets | |
2704 | .El | |
2705 | .It Xo | |
2706 | .Nm | |
2707 | .Cm rollback | |
2708 | .Op Fl Rfr | |
2709 | .Ar snapshot | |
2710 | .Xc | |
2711 | Roll back the given dataset to a previous snapshot. | |
2712 | When a dataset is rolled back, all data that has changed since the snapshot is | |
2713 | discarded, and the dataset reverts to the state at the time of the snapshot. | |
2714 | By default, the command refuses to roll back to a snapshot other than the most | |
2715 | recent one. | |
2716 | In order to do so, all intermediate snapshots and bookmarks must be destroyed by | |
2717 | specifying the | |
2718 | .Fl r | |
2719 | option. | |
2720 | .Pp | |
2721 | The | |
2722 | .Fl rR | |
2723 | options do not recursively destroy the child snapshots of a recursive snapshot. | |
2724 | Only direct snapshots of the specified filesystem are destroyed by either of | |
2725 | these options. | |
2726 | To completely roll back a recursive snapshot, you must rollback the individual | |
2727 | child snapshots. | |
2728 | .Bl -tag -width "-R" | |
2729 | .It Fl R | |
2730 | Destroy any more recent snapshots and bookmarks, as well as any clones of those | |
2731 | snapshots. | |
2732 | .It Fl f | |
2733 | Used with the | |
2734 | .Fl R | |
2735 | option to force an unmount of any clone file systems that are to be destroyed. | |
2736 | .It Fl r | |
da536844 | 2737 | Destroy any snapshots and bookmarks more recent than the one specified. |
44f09cdc BB |
2738 | .El |
2739 | .It Xo | |
2740 | .Nm | |
2741 | .Cm clone | |
2742 | .Op Fl p | |
2743 | .Oo Fl o Ar property Ns = Ns Ar value Oc Ns ... | |
2744 | .Ar snapshot Ar filesystem Ns | Ns Ar volume | |
2745 | .Xc | |
2746 | Creates a clone of the given snapshot. | |
2747 | See the | |
2748 | .Sx Clones | |
2749 | section for details. | |
2750 | The target dataset can be located anywhere in the ZFS hierarchy, and is created | |
2751 | as the same type as the original. | |
2752 | .Bl -tag -width "-o" | |
2753 | .It Fl o Ar property Ns = Ns Ar value | |
2754 | Sets the specified property; see | |
2755 | .Nm zfs Cm create | |
2756 | for details. | |
2757 | .It Fl p | |
2758 | Creates all the non-existing parent datasets. | |
2759 | Datasets created in this manner are automatically mounted according to the | |
2760 | .Sy mountpoint | |
2761 | property inherited from their parent. | |
2762 | If the target filesystem or volume already exists, the operation completes | |
2763 | successfully. | |
2764 | .El | |
2765 | .It Xo | |
2766 | .Nm | |
2767 | .Cm promote | |
2768 | .Ar clone-filesystem | |
2769 | .Xc | |
2770 | Promotes a clone file system to no longer be dependent on its | |
2771 | .Qq origin | |
2772 | snapshot. | |
2773 | This makes it possible to destroy the file system that the clone was created | |
2774 | from. | |
2775 | The clone parent-child dependency relationship is reversed, so that the origin | |
2776 | file system becomes a clone of the specified file system. | |
2777 | .Pp | |
2778 | The snapshot that was cloned, and any snapshots previous to this snapshot, are | |
2779 | now owned by the promoted clone. | |
2780 | The space they use moves from the origin file system to the promoted clone, so | |
2781 | enough space must be available to accommodate these snapshots. | |
2782 | No new space is consumed by this operation, but the space accounting is | |
2783 | adjusted. | |
2784 | The promoted clone must not have any conflicting snapshot names of its own. | |
2785 | The | |
2786 | .Cm rename | |
2787 | subcommand can be used to rename any conflicting snapshots. | |
2788 | .It Xo | |
2789 | .Nm | |
2790 | .Cm rename | |
2791 | .Op Fl f | |
2792 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
2793 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
2794 | .Xc | |
2795 | .It Xo | |
2796 | .Nm | |
2797 | .Cm rename | |
2798 | .Op Fl fp | |
2799 | .Ar filesystem Ns | Ns Ar volume | |
2800 | .Ar filesystem Ns | Ns Ar volume | |
2801 | .Xc | |
2802 | Renames the given dataset. | |
2803 | The new target can be located anywhere in the ZFS hierarchy, with the exception | |
2804 | of snapshots. | |
2805 | Snapshots can only be renamed within the parent file system or volume. | |
2806 | When renaming a snapshot, the parent file system of the snapshot does not need | |
2807 | to be specified as part of the second argument. | |
2808 | Renamed file systems can inherit new mount points, in which case they are | |
2809 | unmounted and remounted at the new mount point. | |
2810 | .Bl -tag -width "-a" | |
2811 | .It Fl f | |
db49968e | 2812 | Force unmount any filesystems that need to be unmounted in the process. |
44f09cdc BB |
2813 | .It Fl p |
2814 | Creates all the nonexistent parent datasets. | |
2815 | Datasets created in this manner are automatically mounted according to the | |
2816 | .Sy mountpoint | |
2817 | property inherited from their parent. | |
2818 | .El | |
2819 | .It Xo | |
2820 | .Nm | |
2821 | .Cm rename | |
2822 | .Fl r | |
2823 | .Ar snapshot Ar snapshot | |
2824 | .Xc | |
2825 | Recursively rename the snapshots of all descendent datasets. | |
2826 | Snapshots are the only dataset that can be renamed recursively. | |
2827 | .It Xo | |
2828 | .Nm | |
2829 | .Cm list | |
2830 | .Op Fl r Ns | Ns Fl d Ar depth | |
2831 | .Op Fl Hp | |
2832 | .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns ... Oc | |
2833 | .Oo Fl s Ar property Oc Ns ... | |
2834 | .Oo Fl S Ar property Oc Ns ... | |
2835 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
2836 | .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns ... | |
2837 | .Xc | |
2838 | Lists the property information for the given datasets in tabular form. | |
2839 | If specified, you can list property information by the absolute pathname or the | |
2840 | relative pathname. | |
2841 | By default, all file systems and volumes are displayed. | |
2842 | Snapshots are displayed if the | |
2843 | .Sy listsnaps | |
2844 | property is | |
2845 | .Sy on | |
2846 | .Po the default is | |
2847 | .Sy off | |
2848 | .Pc . | |
7106b236 AR |
2849 | The following fields are displayed: |
2850 | .Sy name Ns \&, Sy used Ns \&, Sy available Ns \&, Sy referenced Ns \&, Sy mountpoint Ns . | |
44f09cdc BB |
2851 | .Bl -tag -width "-H" |
2852 | .It Fl H | |
2853 | Used for scripting mode. | |
2854 | Do not print headers and separate fields by a single tab instead of arbitrary | |
2855 | white space. | |
2856 | .It Fl S Ar property | |
2857 | Same as the | |
2858 | .Fl s | |
2859 | option, but sorts by property in descending order. | |
2860 | .It Fl d Ar depth | |
2861 | Recursively display any children of the dataset, limiting the recursion to | |
2862 | .Ar depth . | |
2863 | A | |
2864 | .Ar depth | |
2865 | of | |
2866 | .Sy 1 | |
2867 | will display only the dataset and its direct children. | |
2868 | .It Fl o Ar property | |
2869 | A comma-separated list of properties to display. | |
2870 | The property must be: | |
2871 | .Bl -bullet | |
2872 | .It | |
2873 | One of the properties described in the | |
2874 | .Sx Native Properties | |
2875 | section | |
2876 | .It | |
058ac9ba | 2877 | A user property |
44f09cdc BB |
2878 | .It |
2879 | The value | |
2880 | .Sy name | |
2881 | to display the dataset name | |
2882 | .It | |
2883 | The value | |
2884 | .Sy space | |
2885 | to display space usage properties on file systems and volumes. | |
2886 | This is a shortcut for specifying | |
d7323e79 GDN |
2887 | .Fl o Sy name Ns \&, Ns Sy avail Ns \&, Ns Sy used Ns \&, Ns Sy usedsnap Ns \&, Ns |
2888 | .Sy usedds Ns \&, Ns Sy usedrefreserv Ns \&, Ns Sy usedchild Fl t | |
2889 | .Sy filesystem Ns \&, Ns Sy volume | |
44f09cdc BB |
2890 | syntax. |
2891 | .El | |
2892 | .It Fl p | |
2893 | Display numbers in parsable | |
2894 | .Pq exact | |
2895 | values. | |
2896 | .It Fl r | |
2897 | Recursively display any children of the dataset on the command line. | |
2898 | .It Fl s Ar property | |
2899 | A property for sorting the output by column in ascending order based on the | |
2900 | value of the property. | |
2901 | The property must be one of the properties described in the | |
2902 | .Sx Properties | |
9810410a | 2903 | section or the value |
44f09cdc BB |
2904 | .Sy name |
2905 | to sort by the dataset name. | |
2906 | Multiple properties can be specified at one time using multiple | |
2907 | .Fl s | |
2908 | property options. | |
2909 | Multiple | |
2910 | .Fl s | |
2911 | options are evaluated from left to right in decreasing order of importance. | |
058ac9ba | 2912 | The following is a list of sorting criteria: |
44f09cdc BB |
2913 | .Bl -bullet |
2914 | .It | |
058ac9ba | 2915 | Numeric types sort in numeric order. |
44f09cdc | 2916 | .It |
058ac9ba | 2917 | String types sort in alphabetical order. |
44f09cdc BB |
2918 | .It |
2919 | Types inappropriate for a row sort that row to the literal bottom, regardless of | |
2920 | the specified ordering. | |
2921 | .El | |
2922 | .Pp | |
2923 | If no sorting options are specified the existing behavior of | |
2924 | .Nm zfs Cm list | |
2925 | is preserved. | |
2926 | .It Fl t Ar type | |
2927 | A comma-separated list of types to display, where | |
2928 | .Ar type | |
2929 | is one of | |
2930 | .Sy filesystem , | |
2931 | .Sy snapshot , | |
2932 | .Sy volume , | |
2933 | .Sy bookmark , | |
2934 | or | |
2935 | .Sy all . | |
2936 | For example, specifying | |
2937 | .Fl t Sy snapshot | |
2938 | displays only snapshots. | |
2939 | .El | |
2940 | .It Xo | |
2941 | .Nm | |
2942 | .Cm set | |
2943 | .Ar property Ns = Ns Ar value Oo Ar property Ns = Ns Ar value Oc Ns ... | |
2944 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... | |
2945 | .Xc | |
23de906c | 2946 | Sets the property or list of properties to the given value(s) for each dataset. |
44f09cdc BB |
2947 | Only some properties can be edited. |
2948 | See the | |
2949 | .Sx Properties | |
2950 | section for more information on what properties can be set and acceptable | |
2951 | values. | |
2952 | Numeric values can be specified as exact values, or in a human-readable form | |
2953 | with a suffix of | |
2954 | .Sy B , K , M , G , T , P , E , Z | |
2955 | .Po for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, exabytes, | |
2956 | or zettabytes, respectively | |
2957 | .Pc . | |
2958 | User properties can be set on snapshots. | |
2959 | For more information, see the | |
2960 | .Sx User Properties | |
2961 | section. | |
2962 | .It Xo | |
2963 | .Nm | |
2964 | .Cm get | |
2965 | .Op Fl r Ns | Ns Fl d Ar depth | |
2966 | .Op Fl Hp | |
2967 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
2968 | .Oo Fl s Ar source Ns Oo , Ns Ar source Oc Ns ... Oc | |
2969 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
2970 | .Cm all | Ar property Ns Oo , Ns Ar property Oc Ns ... | |
48b0b649 | 2971 | .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns | Ns Ar bookmark Oc Ns ... |
44f09cdc BB |
2972 | .Xc |
2973 | Displays properties for the given datasets. | |
2974 | If no datasets are specified, then the command displays properties for all | |
2975 | datasets on the system. | |
2976 | For each property, the following columns are displayed: | |
2977 | .Bd -literal | |
058ac9ba | 2978 | name Dataset name |
44f09cdc BB |
2979 | property Property name |
2980 | value Property value | |
bd9c1958 CS |
2981 | source Property source \fBlocal\fP, \fBdefault\fP, \fBinherited\fP, |
2982 | \fBtemporary\fP, \fBreceived\fP or none (\fB-\fP). | |
44f09cdc BB |
2983 | .Ed |
2984 | .Pp | |
2985 | All columns are displayed by default, though this can be controlled by using the | |
2986 | .Fl o | |
2987 | option. | |
2988 | This command takes a comma-separated list of properties as described in the | |
2989 | .Sx Native Properties | |
2990 | and | |
2991 | .Sx User Properties | |
2992 | sections. | |
2993 | .Pp | |
9810410a | 2994 | The value |
44f09cdc BB |
2995 | .Sy all |
2996 | can be used to display all properties that apply to the given dataset's type | |
2997 | .Pq filesystem, volume, snapshot, or bookmark . | |
2998 | .Bl -tag -width "-H" | |
2999 | .It Fl H | |
3000 | Display output in a form more easily parsed by scripts. | |
3001 | Any headers are omitted, and fields are explicitly separated by a single tab | |
3002 | instead of an arbitrary amount of space. | |
3003 | .It Fl d Ar depth | |
3004 | Recursively display any children of the dataset, limiting the recursion to | |
3005 | .Ar depth . | |
3006 | A depth of | |
3007 | .Sy 1 | |
3008 | will display only the dataset and its direct children. | |
3009 | .It Fl o Ar field | |
3010 | A comma-separated list of columns to display. | |
d7323e79 | 3011 | .Sy name Ns \&, Ns Sy property Ns \&, Ns Sy value Ns \&, Ns Sy source |
44f09cdc BB |
3012 | is the default value. |
3013 | .It Fl p | |
3014 | Display numbers in parsable | |
3015 | .Pq exact | |
3016 | values. | |
3017 | .It Fl r | |
058ac9ba | 3018 | Recursively display properties for any children. |
44f09cdc BB |
3019 | .It Fl s Ar source |
3020 | A comma-separated list of sources to display. | |
3021 | Those properties coming from a source other than those in this list are ignored. | |
3022 | Each source must be one of the following: | |
3023 | .Sy local , | |
3024 | .Sy default , | |
3025 | .Sy inherited , | |
3026 | .Sy temporary , | |
bd9c1958 | 3027 | .Sy received , |
44f09cdc BB |
3028 | and |
3029 | .Sy none . | |
3030 | The default value is all sources. | |
3031 | .It Fl t Ar type | |
3032 | A comma-separated list of types to display, where | |
3033 | .Ar type | |
3034 | is one of | |
3035 | .Sy filesystem , | |
3036 | .Sy snapshot , | |
3037 | .Sy volume , | |
3038 | .Sy bookmark , | |
3039 | or | |
3040 | .Sy all . | |
3041 | .El | |
3042 | .It Xo | |
3043 | .Nm | |
3044 | .Cm inherit | |
3045 | .Op Fl rS | |
3046 | .Ar property Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Ns ... | |
3047 | .Xc | |
3048 | Clears the specified property, causing it to be inherited from an ancestor, | |
3049 | restored to default if no ancestor has the property set, or with the | |
3050 | .Fl S | |
3051 | option reverted to the received value if one exists. | |
3052 | See the | |
3053 | .Sx Properties | |
3054 | section for a listing of default values, and details on which properties can be | |
3055 | inherited. | |
3056 | .Bl -tag -width "-r" | |
3057 | .It Fl r | |
058ac9ba | 3058 | Recursively inherit the given property for all children. |
44f09cdc | 3059 | .It Fl S |
0bf8501a | 3060 | Revert the property to the received value if one exists; otherwise operate as |
44f09cdc BB |
3061 | if the |
3062 | .Fl S | |
3063 | option was not specified. | |
3064 | .El | |
3065 | .It Xo | |
3066 | .Nm | |
3067 | .Cm upgrade | |
3068 | .Xc | |
058ac9ba | 3069 | Displays a list of file systems that are not the most recent version. |
44f09cdc BB |
3070 | .It Xo |
3071 | .Nm | |
3072 | .Cm upgrade | |
3073 | .Fl v | |
3074 | .Xc | |
3075 | Displays a list of currently supported file system versions. | |
3076 | .It Xo | |
3077 | .Nm | |
3078 | .Cm upgrade | |
3079 | .Op Fl r | |
3080 | .Op Fl V Ar version | |
3081 | .Fl a | Ar filesystem | |
3082 | .Xc | |
3083 | Upgrades file systems to a new on-disk version. | |
3084 | Once this is done, the file systems will no longer be accessible on systems | |
3085 | running older versions of the software. | |
3086 | .Nm zfs Cm send | |
3087 | streams generated from new snapshots of these file systems cannot be accessed on | |
3088 | systems running older versions of the software. | |
3089 | .Pp | |
3090 | In general, the file system version is independent of the pool version. | |
3091 | See | |
3092 | .Xr zpool 8 | |
3093 | for information on the | |
3094 | .Nm zpool Cm upgrade | |
3095 | command. | |
3096 | .Pp | |
3097 | In some cases, the file system version and the pool version are interrelated and | |
3098 | the pool version must be upgraded before the file system version can be | |
3099 | upgraded. | |
3100 | .Bl -tag -width "-V" | |
3101 | .It Fl V Ar version | |
3102 | Upgrade to the specified | |
3103 | .Ar version . | |
3104 | If the | |
3105 | .Fl V | |
3106 | flag is not specified, this command upgrades to the most recent version. | |
3107 | This | |
3108 | option can only be used to increase the version number, and only up to the most | |
3109 | recent version supported by this software. | |
3110 | .It Fl a | |
3111 | Upgrade all file systems on all imported pools. | |
3112 | .It Ar filesystem | |
3113 | Upgrade the specified file system. | |
3114 | .It Fl r | |
3115 | Upgrade the specified file system and all descendent file systems. | |
3116 | .El | |
3117 | .It Xo | |
3118 | .Nm | |
3119 | .Cm userspace | |
3120 | .Op Fl Hinp | |
3121 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
3122 | .Oo Fl s Ar field Oc Ns ... | |
3123 | .Oo Fl S Ar field Oc Ns ... | |
3124 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
3125 | .Ar filesystem Ns | Ns Ar snapshot | |
3126 | .Xc | |
3127 | Displays space consumed by, and quotas on, each user in the specified filesystem | |
3128 | or snapshot. | |
3129 | This corresponds to the | |
3130 | .Sy userused@ Ns Em user , | |
3131 | .Sy userobjused@ Ns Em user , | |
3132 | .Sy userquota@ Ns Em user, | |
3133 | and | |
3134 | .Sy userobjquota@ Ns Em user | |
3135 | properties. | |
3136 | .Bl -tag -width "-H" | |
3137 | .It Fl H | |
3138 | Do not print headers, use tab-delimited output. | |
3139 | .It Fl S Ar field | |
3140 | Sort by this field in reverse order. | |
3141 | See | |
3142 | .Fl s . | |
3143 | .It Fl i | |
3144 | Translate SID to POSIX ID. | |
3145 | The POSIX ID may be ephemeral if no mapping exists. | |
3146 | Normal POSIX interfaces | |
3147 | .Po for example, | |
3148 | .Xr stat 2 , | |
3149 | .Nm ls Fl l | |
3150 | .Pc | |
3151 | perform this translation, so the | |
3152 | .Fl i | |
3153 | option allows the output from | |
3154 | .Nm zfs Cm userspace | |
3155 | to be compared directly with those utilities. | |
3156 | However, | |
3157 | .Fl i | |
5990da81 | 3158 | may lead to confusion if some files were created by an SMB user before a |
44f09cdc BB |
3159 | SMB-to-POSIX name mapping was established. |
3160 | In such a case, some files will be owned by the SMB entity and some by the POSIX | |
3161 | entity. | |
3162 | However, the | |
3163 | .Fl i | |
3164 | option will report that the POSIX entity has the total usage and quota for both. | |
3165 | .It Fl n | |
3166 | Print numeric ID instead of user/group name. | |
3167 | .It Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... | |
3168 | Display only the specified fields from the following set: | |
3169 | .Sy type , | |
3170 | .Sy name , | |
3171 | .Sy used , | |
3172 | .Sy quota . | |
3173 | The default is to display all fields. | |
3174 | .It Fl p | |
3175 | Use exact | |
3176 | .Pq parsable | |
3177 | numeric output. | |
3178 | .It Fl s Ar field | |
3179 | Sort output by this field. | |
3180 | The | |
3181 | .Fl s | |
3182 | and | |
3183 | .Fl S | |
3184 | flags may be specified multiple times to sort first by one field, then by | |
3185 | another. | |
3186 | The default is | |
3187 | .Fl s Sy type Fl s Sy name . | |
3188 | .It Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... | |
3189 | Print only the specified types from the following set: | |
3190 | .Sy all , | |
3191 | .Sy posixuser , | |
3192 | .Sy smbuser , | |
3193 | .Sy posixgroup , | |
3194 | .Sy smbgroup . | |
3195 | The default is | |
d7323e79 | 3196 | .Fl t Sy posixuser Ns \&, Ns Sy smbuser . |
44f09cdc BB |
3197 | The default can be changed to include group types. |
3198 | .El | |
3199 | .It Xo | |
3200 | .Nm | |
3201 | .Cm groupspace | |
3202 | .Op Fl Hinp | |
3203 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
3204 | .Oo Fl s Ar field Oc Ns ... | |
3205 | .Oo Fl S Ar field Oc Ns ... | |
3206 | .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns ... Oc | |
3207 | .Ar filesystem Ns | Ns Ar snapshot | |
3208 | .Xc | |
5990da81 | 3209 | Displays space consumed by, and quotas on, each group in the specified |
44f09cdc BB |
3210 | filesystem or snapshot. |
3211 | This subcommand is identical to | |
3212 | .Nm zfs Cm userspace , | |
3213 | except that the default types to display are | |
d7323e79 | 3214 | .Fl t Sy posixgroup Ns \&, Ns Sy smbgroup . |
44f09cdc BB |
3215 | .It Xo |
3216 | .Nm | |
9c5167d1 NF |
3217 | .Cm projectspace |
3218 | .Op Fl Hp | |
3219 | .Oo Fl o Ar field Ns Oo , Ns Ar field Oc Ns ... Oc | |
3220 | .Oo Fl s Ar field Oc Ns ... | |
3221 | .Oo Fl S Ar field Oc Ns ... | |
3222 | .Ar filesystem Ns | Ns Ar snapshot | |
3223 | .Xc | |
3224 | Displays space consumed by, and quotas on, each project in the specified | |
3225 | filesystem or snapshot. This subcommand is identical to | |
3226 | .Nm zfs Cm userspace , | |
3227 | except that the project identifier is numeral, not name. So need neither | |
3228 | the option | |
3229 | .Sy -i | |
3230 | for SID to POSIX ID nor | |
3231 | .Sy -n | |
3232 | for numeric ID, nor | |
3233 | .Sy -t | |
3234 | for types. | |
3235 | .It Xo | |
3236 | .Nm | |
3237 | .Cm project | |
3238 | .Oo Fl d Ns | Ns Fl r Ns Oc | |
3239 | .Ar file Ns | Ns Ar directory Ns ... | |
3240 | .Xc | |
3241 | List project identifier (ID) and inherit flag of file(s) or directories. | |
3242 | .Bl -tag -width "-d" | |
3243 | .It Fl d | |
3244 | Show the directory project ID and inherit flag, not its childrens. It will | |
3245 | overwrite the former specified | |
3246 | .Fl r | |
3247 | option. | |
3248 | .It Fl r | |
3249 | Show on subdirectories recursively. It will overwrite the former specified | |
3250 | .Fl d | |
3251 | option. | |
3252 | .El | |
3253 | .It Xo | |
3254 | .Nm | |
3255 | .Cm project | |
3256 | .Fl C | |
3257 | .Oo Fl kr Ns Oc | |
3258 | .Ar file Ns | Ns Ar directory Ns ... | |
3259 | .Xc | |
3260 | Clear project inherit flag and/or ID on the file(s) or directories. | |
3261 | .Bl -tag -width "-k" | |
3262 | .It Fl k | |
3263 | Keep the project ID unchanged. If not specified, the project ID will be reset | |
3264 | as zero. | |
3265 | .It Fl r | |
3266 | Clear on subdirectories recursively. | |
3267 | .El | |
3268 | .It Xo | |
3269 | .Nm | |
3270 | .Cm project | |
3271 | .Fl c | |
3272 | .Oo Fl 0 Ns Oc | |
3273 | .Oo Fl d Ns | Ns Fl r Ns Oc | |
3274 | .Op Fl p Ar id | |
3275 | .Ar file Ns | Ns Ar directory Ns ... | |
3276 | .Xc | |
3277 | Check project ID and inherit flag on the file(s) or directories, report the | |
3278 | entries without project inherit flag or with different project IDs from the | |
3279 | specified (via | |
3280 | .Fl p | |
3281 | option) value or the target directory's project ID. | |
3282 | .Bl -tag -width "-0" | |
3283 | .It Fl 0 | |
3284 | Print file name with a trailing NUL instead of newline (by default), like | |
3285 | "find -print0". | |
3286 | .It Fl d | |
3287 | Check the directory project ID and inherit flag, not its childrens. It will | |
3288 | overwrite the former specified | |
3289 | .Fl r | |
3290 | option. | |
3291 | .It Fl p | |
3292 | Specify the referenced ID for comparing with the target file(s) or directories' | |
3293 | project IDs. If not specified, the target (top) directory's project ID will be | |
3294 | used as the referenced one. | |
3295 | .It Fl r | |
3296 | Check on subdirectories recursively. It will overwrite the former specified | |
3297 | .Fl d | |
3298 | option. | |
3299 | .El | |
3300 | .It Xo | |
3301 | .Nm | |
3302 | .Cm project | |
3303 | .Op Fl p Ar id | |
3304 | .Oo Fl rs Ns Oc | |
3305 | .Ar file Ns | Ns Ar directory Ns ... | |
3306 | .Xc | |
3307 | .Bl -tag -width "-p" | |
3308 | Set project ID and/or inherit flag on the file(s) or directories. | |
3309 | .It Fl p | |
3310 | Set the file(s)' or directories' project ID with the given value. | |
3311 | .It Fl r | |
3312 | Set on subdirectories recursively. | |
3313 | .It Fl s | |
3314 | Set project inherit flag on the given file(s) or directories. It is usually used | |
3315 | for setup tree quota on the directory target with | |
3316 | .Fl r | |
3317 | option specified together. When setup tree quota, by default the directory's | |
3318 | project ID will be set to all its descendants unless you specify the project | |
3319 | ID via | |
3320 | .Fl p | |
3321 | option explicitly. | |
3322 | .El | |
3323 | .It Xo | |
3324 | .Nm | |
44f09cdc BB |
3325 | .Cm mount |
3326 | .Xc | |
3327 | Displays all ZFS file systems currently mounted. | |
3328 | .It Xo | |
3329 | .Nm | |
3330 | .Cm mount | |
b5256303 | 3331 | .Op Fl Olv |
44f09cdc BB |
3332 | .Op Fl o Ar options |
3333 | .Fl a | Ar filesystem | |
3334 | .Xc | |
11f6127a KP |
3335 | Mount ZFS filesystem on a path described by its |
3336 | .Sy mountpoint | |
3337 | property, if the path exists and is empty. If | |
3338 | .Sy mountpoint | |
3339 | is set to | |
3340 | .Em legacy , | |
3341 | the filesystem should be instead mounted using | |
3342 | .Xr mount 8 . | |
44f09cdc BB |
3343 | .Bl -tag -width "-O" |
3344 | .It Fl O | |
11f6127a KP |
3345 | Perform an overlay mount. Allows mounting in non-empty |
3346 | .Sy mountpoint . | |
44f09cdc BB |
3347 | See |
3348 | .Xr mount 8 | |
3349 | for more information. | |
3350 | .It Fl a | |
3351 | Mount all available ZFS file systems. | |
11f6127a | 3352 | Invoked automatically as part of the boot process if configured. |
44f09cdc | 3353 | .It Ar filesystem |
058ac9ba | 3354 | Mount the specified filesystem. |
44f09cdc BB |
3355 | .It Fl o Ar options |
3356 | An optional, comma-separated list of mount options to use temporarily for the | |
3357 | duration of the mount. | |
3358 | See the | |
3359 | .Sx Temporary Mount Point Properties | |
3360 | section for details. | |
b5256303 TC |
3361 | .It Fl l |
3362 | Load keys for encrypted filesystems as they are being mounted. This is | |
3363 | equivalent to executing | |
3364 | .Nm zfs Cm load-key | |
3365 | on each encryption root before mounting it. Note that if a filesystem has a | |
3366 | .Sy keylocation | |
3367 | of | |
3368 | .Sy prompt | |
3369 | this will cause the terminal to interactively block after asking for the key. | |
44f09cdc BB |
3370 | .It Fl v |
3371 | Report mount progress. | |
3372 | .El | |
3373 | .It Xo | |
3374 | .Nm | |
3375 | .Cm unmount | |
3376 | .Op Fl f | |
3377 | .Fl a | Ar filesystem Ns | Ns Ar mountpoint | |
3378 | .Xc | |
3379 | Unmounts currently mounted ZFS file systems. | |
3380 | .Bl -tag -width "-a" | |
3381 | .It Fl a | |
3382 | Unmount all available ZFS file systems. | |
3383 | Invoked automatically as part of the shutdown process. | |
3384 | .It Ar filesystem Ns | Ns Ar mountpoint | |
3385 | Unmount the specified filesystem. | |
3386 | The command can also be given a path to a ZFS file system mount point on the | |
3387 | system. | |
3388 | .It Fl f | |
058ac9ba | 3389 | Forcefully unmount the file system, even if it is currently in use. |
44f09cdc BB |
3390 | .El |
3391 | .It Xo | |
3392 | .Nm | |
3393 | .Cm share | |
3394 | .Fl a | Ar filesystem | |
3395 | .Xc | |
3396 | Shares available ZFS file systems. | |
3397 | .Bl -tag -width "-a" | |
3398 | .It Fl a | |
3399 | Share all available ZFS file systems. | |
3400 | Invoked automatically as part of the boot process. | |
3401 | .It Ar filesystem | |
3402 | Share the specified filesystem according to the | |
3403 | .Sy sharenfs | |
3404 | and | |
3405 | .Sy sharesmb | |
3406 | properties. | |
3407 | File systems are shared when the | |
3408 | .Sy sharenfs | |
3409 | or | |
3410 | .Sy sharesmb | |
3411 | property is set. | |
3412 | .El | |
3413 | .It Xo | |
3414 | .Nm | |
3415 | .Cm unshare | |
3416 | .Fl a | Ar filesystem Ns | Ns Ar mountpoint | |
3417 | .Xc | |
3418 | Unshares currently shared ZFS file systems. | |
3419 | .Bl -tag -width "-a" | |
3420 | .It Fl a | |
3421 | Unshare all available ZFS file systems. | |
3422 | Invoked automatically as part of the shutdown process. | |
3423 | .It Ar filesystem Ns | Ns Ar mountpoint | |
3424 | Unshare the specified filesystem. | |
3425 | The command can also be given a path to a ZFS file system shared on the system. | |
3426 | .El | |
3427 | .It Xo | |
3428 | .Nm | |
3429 | .Cm bookmark | |
3430 | .Ar snapshot bookmark | |
3431 | .Xc | |
3432 | Creates a bookmark of the given snapshot. | |
3433 | Bookmarks mark the point in time when the snapshot was created, and can be used | |
3434 | as the incremental source for a | |
3435 | .Nm zfs Cm send | |
3436 | command. | |
3437 | .Pp | |
da536844 | 3438 | This feature must be enabled to be used. |
44f09cdc BB |
3439 | See |
3440 | .Xr zpool-features 5 | |
3441 | for details on ZFS feature flags and the | |
3442 | .Sy bookmarks | |
3443 | feature. | |
3444 | .It Xo | |
3445 | .Nm | |
3446 | .Cm send | |
9c5e88b1 | 3447 | .Op Fl DLPRbcehnpvw |
44f09cdc BB |
3448 | .Op Oo Fl I Ns | Ns Fl i Oc Ar snapshot |
3449 | .Ar snapshot | |
3450 | .Xc | |
3451 | Creates a stream representation of the second | |
3452 | .Ar snapshot , | |
3453 | which is written to standard output. | |
3454 | The output can be redirected to a file or to a different system | |
3455 | .Po for example, using | |
3456 | .Xr ssh 1 | |
3457 | .Pc . | |
3458 | By default, a full stream is generated. | |
3459 | .Bl -tag -width "-D" | |
3460 | .It Fl D, -dedup | |
3461 | Generate a deduplicated stream. | |
3462 | Blocks which would have been sent multiple times in the send stream will only be | |
3463 | sent once. | |
3464 | The receiving system must also support this feature to receive a deduplicated | |
3465 | stream. | |
3466 | This flag can be used regardless of the dataset's | |
3467 | .Sy dedup | |
3468 | property, but performance will be much better if the filesystem uses a | |
3469 | dedup-capable checksum | |
3470 | .Po for example, | |
3471 | .Sy sha256 | |
3472 | .Pc . | |
3473 | .It Fl I Ar snapshot | |
3474 | Generate a stream package that sends all intermediary snapshots from the first | |
3475 | snapshot to the second snapshot. | |
3476 | For example, | |
3477 | .Fl I Em @a Em fs@d | |
3478 | is similar to | |
d7323e79 | 3479 | .Fl i Em @a Em fs@b Ns \&; Fl i Em @b Em fs@c Ns \&; Fl i Em @c Em fs@d . |
44f09cdc BB |
3480 | The incremental source may be specified as with the |
3481 | .Fl i | |
3482 | option. | |
3483 | .It Fl L, -large-block | |
3484 | Generate a stream which may contain blocks larger than 128KB. | |
3485 | This flag has no effect if the | |
3486 | .Sy large_blocks | |
3487 | pool feature is disabled, or if the | |
3488 | .Sy recordsize | |
3489 | property of this filesystem has never been set above 128KB. | |
3490 | The receiving system must have the | |
3491 | .Sy large_blocks | |
3492 | pool feature enabled as well. | |
3493 | See | |
3494 | .Xr zpool-features 5 | |
3495 | for details on ZFS feature flags and the | |
3496 | .Sy large_blocks | |
3497 | feature. | |
3498 | .It Fl P, -parsable | |
9566fb1a | 3499 | Print machine-parsable verbose information about the stream package generated. |
44f09cdc BB |
3500 | .It Fl R, -replicate |
3501 | Generate a replication stream package, which will replicate the specified | |
3502 | file system, and all descendent file systems, up to the named snapshot. | |
3503 | When received, all properties, snapshots, descendent file systems, and clones | |
3504 | are preserved. | |
3505 | .Pp | |
3506 | If the | |
3507 | .Fl i | |
3508 | or | |
3509 | .Fl I | |
3510 | flags are used in conjunction with the | |
3511 | .Fl R | |
3512 | flag, an incremental replication stream is generated. | |
3513 | The current values of properties, and current snapshot and file system names are | |
3514 | set when the stream is received. | |
3515 | If the | |
3516 | .Fl F | |
3517 | flag is specified when this stream is received, snapshots and file systems that | |
dd29864b TC |
3518 | do not exist on the sending side are destroyed. If the |
3519 | .Fl R | |
3520 | flag is used to send encrypted datasets, then | |
3521 | .Fl w | |
3522 | must also be specified. | |
44f09cdc BB |
3523 | .It Fl e, -embed |
3524 | Generate a more compact stream by using | |
3525 | .Sy WRITE_EMBEDDED | |
3526 | records for blocks which are stored more compactly on disk by the | |
3527 | .Sy embedded_data | |
3528 | pool feature. | |
3529 | This flag has no effect if the | |
3530 | .Sy embedded_data | |
3531 | feature is disabled. | |
3532 | The receiving system must have the | |
3533 | .Sy embedded_data | |
3534 | feature enabled. | |
3535 | If the | |
3536 | .Sy lz4_compress | |
3537 | feature is active on the sending system, then the receiving system must have | |
4807c0ba TC |
3538 | that feature enabled as well. Datasets that are sent with this flag may not be |
3539 | received as an encrypted dataset, since encrypted datasets cannot use the | |
3540 | .Sy embedded_data | |
3541 | feature. | |
44f09cdc BB |
3542 | See |
3543 | .Xr zpool-features 5 | |
3544 | for details on ZFS feature flags and the | |
3545 | .Sy embedded_data | |
3546 | feature. | |
faa97c16 | 3547 | .It Fl b, -backup |
3548 | Sends only received property values whether or not they are overridden by local | |
3549 | settings, but only if the dataset has ever been received. Use this option when | |
3550 | you want | |
3551 | .Nm zfs Cm receive | |
3552 | to restore received properties backed up on the sent dataset and to avoid | |
3553 | sending local settings that may have nothing to do with the source dataset, | |
3554 | but only with how the data is backed up. | |
44f09cdc | 3555 | .It Fl c, -compressed |
2aa34383 | 3556 | Generate a more compact stream by using compressed WRITE records for blocks |
44f09cdc BB |
3557 | which are compressed on disk and in memory |
3558 | .Po see the | |
3559 | .Sy compression | |
3560 | property for details | |
3561 | .Pc . | |
3562 | If the | |
3563 | .Sy lz4_compress | |
3564 | feature is active on the sending system, then the receiving system must have | |
3565 | that feature enabled as well. | |
3566 | If the | |
3567 | .Sy large_blocks | |
3568 | feature is enabled on the sending system but the | |
3569 | .Fl L | |
3570 | option is not supplied in conjunction with | |
3571 | .Fl c , | |
3572 | then the data will be decompressed before sending so it can be split into | |
3573 | smaller block sizes. | |
b5256303 TC |
3574 | .It Fl w, -raw |
3575 | For encrypted datasets, send data exactly as it exists on disk. This allows | |
3576 | backups to be taken even if encryption keys are not currently loaded. The | |
3577 | backup may then be received on an untrusted machine since that machine will | |
3578 | not have the encryption keys to read the protected data or alter it without | |
3579 | being detected. Upon being received, the dataset will have the same encryption | |
3580 | keys as it did on the send side, although the | |
3581 | .Sy keylocation | |
3582 | property will be defaulted to | |
3583 | .Sy prompt | |
3584 | if not otherwise provided. For unencrypted datasets, this flag will be | |
3585 | equivalent to | |
3586 | .Fl Lec . | |
3587 | Note that if you do not use this flag for sending encrypted datasets, data will | |
3588 | be sent unencrypted and may be re-encrypted with a different encryption key on | |
3589 | the receiving system, which will disable the ability to do a raw send to that | |
3590 | system for incrementals. | |
9c5e88b1 PZ |
3591 | .It Fl h, -holds |
3592 | Generate a stream package that includes any snapshot holds (created with the | |
3593 | .Sy zfs hold | |
3594 | command), and indicating to | |
dd29864b | 3595 | .Sy zfs receive |
9c5e88b1 | 3596 | that the holds be applied to the dataset on the receiving system. |
44f09cdc BB |
3597 | .It Fl i Ar snapshot |
3598 | Generate an incremental stream from the first | |
3599 | .Ar snapshot | |
3600 | .Pq the incremental source | |
3601 | to the second | |
3602 | .Ar snapshot | |
3603 | .Pq the incremental target . | |
3604 | The incremental source can be specified as the last component of the snapshot | |
3605 | name | |
3606 | .Po the | |
3607 | .Sy @ | |
3608 | character and following | |
3609 | .Pc | |
3610 | and it is assumed to be from the same file system as the incremental target. | |
3611 | .Pp | |
3612 | If the destination is a clone, the source may be the origin snapshot, which must | |
3613 | be fully specified | |
3614 | .Po for example, | |
3615 | .Em pool/fs@origin , | |
3616 | not just | |
3617 | .Em @origin | |
3618 | .Pc . | |
3619 | .It Fl n, -dryrun | |
3620 | Do a dry-run | |
3621 | .Pq Qq No-op | |
3622 | send. | |
3623 | Do not generate any actual send data. | |
3624 | This is useful in conjunction with the | |
3625 | .Fl v | |
3626 | or | |
3627 | .Fl P | |
3628 | flags to determine what data will be sent. | |
3629 | In this case, the verbose output will be written to standard output | |
3630 | .Po contrast with a non-dry-run, where the stream is written to standard output | |
3631 | and the verbose output goes to standard error | |
3632 | .Pc . | |
3633 | .It Fl p, -props | |
3634 | Include the dataset's properties in the stream. | |
3635 | This flag is implicit when | |
3636 | .Fl R | |
3637 | is specified. | |
4807c0ba TC |
3638 | The receiving system must also support this feature. Sends of encrypted datasets |
3639 | must use | |
3640 | .Fl w | |
3641 | when using this flag. | |
44f09cdc BB |
3642 | .It Fl v, -verbose |
3643 | Print verbose information about the stream package generated. | |
3644 | This information includes a per-second report of how much data has been sent. | |
3645 | .Pp | |
3646 | The format of the stream is committed. | |
29179568 | 3647 | You will be able to receive your streams on future versions of ZFS. |
835db585 | 3648 | .El |
44f09cdc BB |
3649 | .It Xo |
3650 | .Nm | |
3651 | .Cm send | |
835db585 | 3652 | .Op Fl LPcenvw |
44f09cdc BB |
3653 | .Op Fl i Ar snapshot Ns | Ns Ar bookmark |
3654 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
3655 | .Xc | |
3656 | Generate a send stream, which may be of a filesystem, and may be incremental | |
3657 | from a bookmark. | |
3658 | If the destination is a filesystem or volume, the pool must be read-only, or the | |
3659 | filesystem must not be mounted. | |
3660 | When the stream generated from a filesystem or volume is received, the default | |
3661 | snapshot name will be | |
3662 | .Qq --head-- . | |
3663 | .Bl -tag -width "-L" | |
3664 | .It Fl L, -large-block | |
3665 | Generate a stream which may contain blocks larger than 128KB. | |
3666 | This flag has no effect if the | |
3667 | .Sy large_blocks | |
3668 | pool feature is disabled, or if the | |
3669 | .Sy recordsize | |
3670 | property of this filesystem has never been set above 128KB. | |
3671 | The receiving system must have the | |
3672 | .Sy large_blocks | |
3673 | pool feature enabled as well. | |
3674 | See | |
3675 | .Xr zpool-features 5 | |
3676 | for details on ZFS feature flags and the | |
3677 | .Sy large_blocks | |
3678 | feature. | |
835db585 | 3679 | .It Fl P, -parsable |
3680 | Print machine-parsable verbose information about the stream package generated. | |
44f09cdc BB |
3681 | .It Fl c, -compressed |
3682 | Generate a more compact stream by using compressed WRITE records for blocks | |
3683 | which are compressed on disk and in memory | |
3684 | .Po see the | |
3685 | .Sy compression | |
3686 | property for details | |
3687 | .Pc . | |
3688 | If the | |
3689 | .Sy lz4_compress | |
3690 | feature is active on the sending system, then the receiving system must have | |
3691 | that feature enabled as well. | |
3692 | If the | |
3693 | .Sy large_blocks | |
3694 | feature is enabled on the sending system but the | |
3695 | .Fl L | |
3696 | option is not supplied in conjunction with | |
3697 | .Fl c , | |
3698 | then the data will be decompressed before sending so it can be split into | |
3699 | smaller block sizes. | |
b5256303 TC |
3700 | .It Fl w, -raw |
3701 | For encrypted datasets, send data exactly as it exists on disk. This allows | |
3702 | backups to be taken even if encryption keys are not currently loaded. The | |
3703 | backup may then be received on an untrusted machine since that machine will | |
3704 | not have the encryption keys to read the protected data or alter it without | |
3705 | being detected. Upon being received, the dataset will have the same encryption | |
3706 | keys as it did on the send side, although the | |
3707 | .Sy keylocation | |
3708 | property will be defaulted to | |
3709 | .Sy prompt | |
3710 | if not otherwise provided. For unencrypted datasets, this flag will be | |
3711 | equivalent to | |
3712 | .Fl Lec . | |
3713 | Note that if you do not use this flag for sending encrypted datasets, data will | |
3714 | be sent unencrypted and may be re-encrypted with a different encryption key on | |
3715 | the receiving system, which will disable the ability to do a raw send to that | |
3716 | system for incrementals. | |
44f09cdc BB |
3717 | .It Fl e, -embed |
3718 | Generate a more compact stream by using | |
3719 | .Sy WRITE_EMBEDDED | |
3720 | records for blocks which are stored more compactly on disk by the | |
3721 | .Sy embedded_data | |
3722 | pool feature. | |
3723 | This flag has no effect if the | |
3724 | .Sy embedded_data | |
3725 | feature is disabled. | |
3726 | The receiving system must have the | |
3727 | .Sy embedded_data | |
3728 | feature enabled. | |
3729 | If the | |
3730 | .Sy lz4_compress | |
3731 | feature is active on the sending system, then the receiving system must have | |
4807c0ba TC |
3732 | that feature enabled as well. Datasets that are sent with this flag may not be |
3733 | received as an encrypted dataset, since encrypted datasets cannot use the | |
3734 | .Sy embedded_data | |
3735 | feature. | |
44f09cdc BB |
3736 | See |
3737 | .Xr zpool-features 5 | |
3738 | for details on ZFS feature flags and the | |
3739 | .Sy embedded_data | |
3740 | feature. | |
3741 | .It Fl i Ar snapshot Ns | Ns Ar bookmark | |
3742 | Generate an incremental send stream. | |
3743 | The incremental source must be an earlier snapshot in the destination's history. | |
3744 | It will commonly be an earlier snapshot in the destination's file system, in | |
3745 | which case it can be specified as the last component of the name | |
3746 | .Po the | |
3747 | .Sy # | |
3748 | or | |
3749 | .Sy @ | |
3750 | character and following | |
3751 | .Pc . | |
3752 | .Pp | |
3753 | If the incremental target is a clone, the incremental source can be the origin | |
3754 | snapshot, or an earlier snapshot in the origin's filesystem, or the origin's | |
3755 | origin, etc. | |
835db585 | 3756 | .It Fl n, -dryrun |
3757 | Do a dry-run | |
3758 | .Pq Qq No-op | |
3759 | send. | |
3760 | Do not generate any actual send data. | |
3761 | This is useful in conjunction with the | |
3762 | .Fl v | |
3763 | or | |
3764 | .Fl P | |
3765 | flags to determine what data will be sent. | |
3766 | In this case, the verbose output will be written to standard output | |
3767 | .Po contrast with a non-dry-run, where the stream is written to standard output | |
3768 | and the verbose output goes to standard error | |
3769 | .Pc . | |
3770 | .It Fl v, -verbose | |
3771 | Print verbose information about the stream package generated. | |
3772 | This information includes a per-second report of how much data has been sent. | |
44f09cdc BB |
3773 | .El |
3774 | .It Xo | |
3775 | .Nm | |
3776 | .Cm send | |
3777 | .Op Fl Penv | |
3778 | .Fl t | |
3779 | .Ar receive_resume_token | |
3780 | .Xc | |
3781 | Creates a send stream which resumes an interrupted receive. | |
3782 | The | |
3783 | .Ar receive_resume_token | |
3784 | is the value of this property on the filesystem or volume that was being | |
3785 | received into. | |
3786 | See the documentation for | |
3787 | .Sy zfs receive -s | |
3788 | for more details. | |
3789 | .It Xo | |
3790 | .Nm | |
3791 | .Cm receive | |
9c5e88b1 | 3792 | .Op Fl Fhnsuv |
44f09cdc BB |
3793 | .Op Fl o Sy origin Ns = Ns Ar snapshot |
3794 | .Op Fl o Ar property Ns = Ns Ar value | |
3795 | .Op Fl x Ar property | |
3796 | .Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot | |
3797 | .Xc | |
3798 | .It Xo | |
3799 | .Nm | |
3800 | .Cm receive | |
9c5e88b1 | 3801 | .Op Fl Fhnsuv |
44f09cdc BB |
3802 | .Op Fl d Ns | Ns Fl e |
3803 | .Op Fl o Sy origin Ns = Ns Ar snapshot | |
3804 | .Op Fl o Ar property Ns = Ns Ar value | |
3805 | .Op Fl x Ar property | |
3806 | .Ar filesystem | |
3807 | .Xc | |
3808 | Creates a snapshot whose contents are as specified in the stream provided on | |
3809 | standard input. | |
3810 | If a full stream is received, then a new file system is created as well. | |
3811 | Streams are created using the | |
3812 | .Nm zfs Cm send | |
3813 | subcommand, which by default creates a full stream. | |
3814 | .Nm zfs Cm recv | |
3815 | can be used as an alias for | |
3816 | .Nm zfs Cm receive. | |
3817 | .Pp | |
3818 | If an incremental stream is received, then the destination file system must | |
3819 | already exist, and its most recent snapshot must match the incremental stream's | |
3820 | source. | |
3821 | For | |
3822 | .Sy zvols , | |
3823 | the destination device link is destroyed and recreated, which means the | |
3824 | .Sy zvol | |
3825 | cannot be accessed during the | |
3826 | .Cm receive | |
3827 | operation. | |
3828 | .Pp | |
3829 | When a snapshot replication package stream that is generated by using the | |
3830 | .Nm zfs Cm send Fl R | |
3831 | command is received, any snapshots that do not exist on the sending location are | |
3832 | destroyed by using the | |
3833 | .Nm zfs Cm destroy Fl d | |
3834 | command. | |
3835 | .Pp | |
3836 | If | |
90cdf283 | 3837 | .Fl o Em property Ns = Ns Ar value |
44f09cdc | 3838 | or |
90cdf283 | 3839 | .Fl x Em property |
44f09cdc BB |
3840 | is specified, it applies to the effective value of the property throughout |
3841 | the entire subtree of replicated datasets. Effective property values will be | |
3842 | set ( | |
3843 | .Fl o | |
3844 | ) or inherited ( | |
3845 | .Fl x | |
3846 | ) on the topmost in the replicated subtree. In descendant datasets, if the | |
3847 | property is set by the send stream, it will be overridden by forcing the | |
3848 | property to be inherited from the top‐most file system. Received properties | |
3849 | are retained in spite of being overridden and may be restored with | |
3850 | .Nm zfs Cm inherit Fl S . | |
3851 | Specifying | |
90cdf283 | 3852 | .Fl o Sy origin Ns = Ns Em snapshot |
44f09cdc BB |
3853 | is a special case because, even if |
3854 | .Sy origin | |
3855 | is a read-only property and cannot be set, it's allowed to receive the send | |
3856 | stream as a clone of the given snapshot. | |
3857 | .Pp | |
4807c0ba TC |
3858 | Raw encrypted send streams (created with |
3859 | .Nm zfs Cm send Fl w | |
3860 | ) may only be received as is, and cannot be re-encrypted, decrypted, or | |
3861 | recompressed by the receive process. Unencrypted streams can be received as | |
3862 | encrypted datasets, either through inheritance or by specifying encryption | |
3863 | parameters with the | |
3864 | .Fl o | |
dd29864b TC |
3865 | options. Note that the |
3866 | .Sy keylocation | |
3867 | property cannot be overridden to | |
3868 | .Sy prompt | |
3869 | during a receive. This is because the receive process itself is already using | |
3870 | stdin for the send stream. Instead, the property can be overridden after the | |
3871 | receive completes. | |
4807c0ba | 3872 | .Pp |
f00ab3f2 TC |
3873 | The added security provided by raw sends adds some restrictions to the send |
3874 | and receive process. ZFS will not allow a mix of raw receives and non-raw | |
3875 | receives. Specifically, any raw incremental receives that are attempted after | |
3876 | a non-raw receive will fail. Non-raw receives do not have this restriction and, | |
3877 | therefore, are always possible. Because of this, it is best practice to always | |
3878 | use either raw sends for their security benefits or non-raw sends for their | |
3879 | flexibility when working with encrypted datasets, but not a combination. | |
3880 | .Pp | |
3881 | The reason for this restriction stems from the inherent restrictions of the | |
3882 | AEAD ciphers that ZFS uses to encrypt data. When using ZFS native encryption, | |
3883 | each block of data is encrypted against a randomly generated number known as | |
3884 | the "initialization vector" (IV), which is stored in the filesystem metadata. | |
3885 | This number is required by the encryption algorithms whenever the data is to | |
3886 | be decrypted. Together, all of the IVs provided for all of the blocks in a | |
3887 | given snapshot are collectively called an "IV set". When ZFS performs a raw | |
3888 | send, the IV set is transferred from the source to the destination in the send | |
3889 | stream. When ZFS performs a non-raw send, the data is decrypted by the source | |
3890 | system and re-encrypted by the destination system, creating a snapshot with | |
3891 | effectively the same data, but a different IV set. In order for decryption to | |
3892 | work after a raw send, ZFS must ensure that the IV set used on both the source | |
3893 | and destination side match. When an incremental raw receive is performed on | |
3894 | top of an existing snapshot, ZFS will check to confirm that the "from" | |
3895 | snapshot on both the source and destination were using the same IV set, | |
3896 | ensuring the new IV set is consistent. | |
3897 | .Pp | |
44f09cdc BB |
3898 | The name of the snapshot |
3899 | .Pq and file system, if a full stream is received | |
3900 | that this subcommand creates depends on the argument type and the use of the | |
3901 | .Fl d | |
3902 | or | |
3903 | .Fl e | |
3904 | options. | |
3905 | .Pp | |
3906 | If the argument is a snapshot name, the specified | |
3907 | .Ar snapshot | |
3908 | is created. | |
3909 | If the argument is a file system or volume name, a snapshot with the same name | |
3910 | as the sent snapshot is created within the specified | |
3911 | .Ar filesystem | |
3912 | or | |
3913 | .Ar volume . | |
3914 | If neither of the | |
3915 | .Fl d | |
3916 | or | |
3917 | .Fl e | |
3918 | options are specified, the provided target snapshot name is used exactly as | |
3919 | provided. | |
3920 | .Pp | |
3921 | The | |
3922 | .Fl d | |
3923 | and | |
3924 | .Fl e | |
3925 | options cause the file system name of the target snapshot to be determined by | |
3926 | appending a portion of the sent snapshot's name to the specified target | |
3927 | .Ar filesystem . | |
3928 | If the | |
3929 | .Fl d | |
3930 | option is specified, all but the first element of the sent snapshot's file | |
3931 | system path | |
3932 | .Pq usually the pool name | |
3933 | is used and any required intermediate file systems within the specified one are | |
3934 | created. | |
3935 | If the | |
3936 | .Fl e | |
3937 | option is specified, then only the last element of the sent snapshot's file | |
3938 | system name | |
3939 | .Pq i.e. the name of the source file system itself | |
3940 | is used as the target file system name. | |
3941 | .Bl -tag -width "-F" | |
3942 | .It Fl F | |
3943 | Force a rollback of the file system to the most recent snapshot before | |
3944 | performing the receive operation. | |
3945 | If receiving an incremental replication stream | |
3946 | .Po for example, one generated by | |
3947 | .Nm zfs Cm send Fl R Op Fl i Ns | Ns Fl I | |
3948 | .Pc , | |
3949 | destroy snapshots and file systems that do not exist on the sending side. | |
3950 | .It Fl d | |
3951 | Discard the first element of the sent snapshot's file system name, using the | |
3952 | remaining elements to determine the name of the target file system for the new | |
3953 | snapshot as described in the paragraph above. | |
3954 | .It Fl e | |
3955 | Discard all but the last element of the sent snapshot's file system name, using | |
3956 | that element to determine the name of the target file system for the new | |
3957 | snapshot as described in the paragraph above. | |
dd29864b | 3958 | .It Fl h |
9c5e88b1 | 3959 | Skip the receive of holds. There is no effect if holds are not sent. |
44f09cdc BB |
3960 | .It Fl n |
3961 | Do not actually receive the stream. | |
3962 | This can be useful in conjunction with the | |
3963 | .Fl v | |
3964 | option to verify the name the receive operation would use. | |
3965 | .It Fl o Sy origin Ns = Ns Ar snapshot | |
e6d3a843 PD |
3966 | Forces the stream to be received as a clone of the given snapshot. |
3967 | If the stream is a full send stream, this will create the filesystem | |
44f09cdc BB |
3968 | described by the stream as a clone of the specified snapshot. |
3969 | Which snapshot was specified will not affect the success or failure of the | |
3970 | receive, as long as the snapshot does exist. | |
3971 | If the stream is an incremental send stream, all the normal verification will be | |
3972 | performed. | |
90cdf283 | 3973 | .It Fl o Em property Ns = Ns Ar value |
44f09cdc | 3974 | Sets the specified property as if the command |
90cdf283 | 3975 | .Nm zfs Cm set Em property Ns = Ns Ar value |
44f09cdc BB |
3976 | was invoked immediately before the receive. When receiving a stream from |
3977 | .Nm zfs Cm send Fl R , | |
3978 | causes the property to be inherited by all descendant datasets, as through | |
3979 | .Nm zfs Cm inherit Em property | |
3980 | was run on any descendant datasets that have this property set on the | |
3981 | sending system. | |
3982 | .Pp | |
3983 | Any editable property can be set at receive time. Set-once properties bound | |
3984 | to the received data, such as | |
3985 | .Sy normalization | |
3986 | and | |
3987 | .Sy casesensitivity , | |
3988 | cannot be set at receive time even when the datasets are newly created by | |
3989 | .Nm zfs Cm receive . | |
3990 | Additionally both settable properties | |
3991 | .Sy version | |
3992 | and | |
3993 | .Sy volsize | |
3994 | cannot be set at receive time. | |
3995 | .Pp | |
3996 | The | |
3997 | .Fl o | |
3998 | option may be specified multiple times, for different properties. An error | |
3999 | results if the same property is specified in multiple | |
4000 | .Fl o | |
4001 | or | |
4002 | .Fl x | |
4003 | options. | |
d9c460a0 TC |
4004 | .Pp |
4005 | The | |
4006 | .Fl o | |
4007 | option may also be used to override encryption properties upon initial | |
4008 | receive. This allows unencrypted streams to be received as encrypted datasets. | |
4009 | To cause the received dataset (or root dataset of a recursive stream) to be | |
4010 | received as an encryption root, specify encryption properties in the same | |
4011 | manner as is required for | |
4012 | .Nm | |
4013 | .Cm create . | |
4014 | For instance: | |
4015 | .Bd -literal | |
4016 | # zfs send tank/test@snap1 | zfs recv -o encryption=on -o keyformat=passphrase -o keylocation=file:///path/to/keyfile | |
4017 | .Ed | |
4018 | .Pp | |
4019 | Note that | |
4020 | .Op Fl o Ar keylocation Ns = Ns Ar prompt | |
4021 | may not be specified here, since stdin is already being utilized for the send | |
4022 | stream. Once the receive has completed, you can use | |
4023 | .Nm | |
4024 | .Cm set | |
4025 | to change this setting after the fact. Similarly, you can receive a dataset as | |
4026 | an encrypted child by specifying | |
4027 | .Op Fl x Ar encryption | |
4028 | to force the property to be inherited. Overriding encryption properties (except | |
4029 | for | |
4030 | .Sy keylocation Ns ) | |
4031 | is not possible with raw send streams. | |
44f09cdc BB |
4032 | .It Fl s |
4033 | If the receive is interrupted, save the partially received state, rather | |
4034 | than deleting it. | |
4035 | Interruption may be due to premature termination of the stream | |
4036 | .Po e.g. due to network failure or failure of the remote system | |
4037 | if the stream is being read over a network connection | |
4038 | .Pc , | |
4039 | a checksum error in the stream, termination of the | |
4040 | .Nm zfs Cm receive | |
4041 | process, or unclean shutdown of the system. | |
4042 | .Pp | |
4043 | The receive can be resumed with a stream generated by | |
4044 | .Nm zfs Cm send Fl t Ar token , | |
4045 | where the | |
4046 | .Ar token | |
4047 | is the value of the | |
4048 | .Sy receive_resume_token | |
4049 | property of the filesystem or volume which is received into. | |
4050 | .Pp | |
4051 | To use this flag, the storage pool must have the | |
4052 | .Sy extensible_dataset | |
4053 | feature enabled. | |
4054 | See | |
4055 | .Xr zpool-features 5 | |
4056 | for details on ZFS feature flags. | |
4057 | .It Fl u | |
4058 | File system that is associated with the received stream is not mounted. | |
4059 | .It Fl v | |
4060 | Print verbose information about the stream and the time required to perform the | |
4061 | receive operation. | |
4062 | .It Fl x Em property | |
4063 | Ensures that the effective value of the specified property after the | |
4064 | receive is unaffected by the value of that property in the send stream (if any), | |
4065 | as if the property had been excluded from the send stream. | |
4066 | .Pp | |
4067 | If the specified property is not present in the send stream, this option does | |
4068 | nothing. | |
4069 | .Pp | |
4070 | If a received property needs to be overridden, the effective value will be | |
4071 | set or inherited, depending on whether the property is inheritable or not. | |
4072 | .Pp | |
4073 | In the case of an incremental update, | |
4074 | .Fl x | |
4075 | leaves any existing local setting or explicit inheritance unchanged. | |
4076 | .Pp | |
4077 | All | |
4078 | .Fl o | |
9810410a | 4079 | restrictions (e.g. set-once) apply equally to |
44f09cdc BB |
4080 | .Fl x . |
4081 | .El | |
4082 | .It Xo | |
4083 | .Nm | |
4084 | .Cm receive | |
4085 | .Fl A | |
4086 | .Ar filesystem Ns | Ns Ar volume | |
4087 | .Xc | |
4088 | Abort an interrupted | |
4089 | .Nm zfs Cm receive Fl s , | |
4090 | deleting its saved partially received state. | |
4091 | .It Xo | |
4092 | .Nm | |
4093 | .Cm allow | |
4094 | .Ar filesystem Ns | Ns Ar volume | |
4095 | .Xc | |
4096 | Displays permissions that have been delegated on the specified filesystem or | |
4097 | volume. | |
4098 | See the other forms of | |
4099 | .Nm zfs Cm allow | |
4100 | for more information. | |
4101 | .Pp | |
4102 | Delegations are supported under Linux with the exception of | |
4103 | .Sy mount , | |
4104 | .Sy unmount , | |
4105 | .Sy mountpoint , | |
4106 | .Sy canmount , | |
4107 | .Sy rename , | |
4108 | and | |
4109 | .Sy share . | |
4110 | These permissions cannot be delegated because the Linux | |
4111 | .Xr mount 8 | |
4112 | command restricts modifications of the global namespace to the root user. | |
4113 | .It Xo | |
4114 | .Nm | |
4115 | .Cm allow | |
4116 | .Op Fl dglu | |
4117 | .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... | |
4118 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4119 | .Ar setname Oc Ns ... | |
4120 | .Ar filesystem Ns | Ns Ar volume | |
0238a975 | 4121 | .Xc |
4122 | .It Xo | |
44f09cdc BB |
4123 | .Nm |
4124 | .Cm allow | |
4125 | .Op Fl dl | |
4126 | .Fl e Ns | Ns Sy everyone | |
4127 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4128 | .Ar setname Oc Ns ... | |
4129 | .Ar filesystem Ns | Ns Ar volume | |
4130 | .Xc | |
4131 | Delegates ZFS administration permission for the file systems to non-privileged | |
4132 | users. | |
4133 | .Bl -tag -width "-d" | |
4134 | .It Fl d | |
4135 | Allow only for the descendent file systems. | |
4136 | .It Fl e Ns | Ns Sy everyone | |
4137 | Specifies that the permissions be delegated to everyone. | |
4138 | .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns ... | |
4139 | Explicitly specify that permissions are delegated to the group. | |
4140 | .It Fl l | |
4141 | Allow | |
4142 | .Qq locally | |
4143 | only for the specified file system. | |
4144 | .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns ... | |
4145 | Explicitly specify that permissions are delegated to the user. | |
4146 | .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... | |
4147 | Specifies to whom the permissions are delegated. | |
4148 | Multiple entities can be specified as a comma-separated list. | |
4149 | If neither of the | |
4150 | .Fl gu | |
4151 | options are specified, then the argument is interpreted preferentially as the | |
4152 | keyword | |
4153 | .Sy everyone , | |
4154 | then as a user name, and lastly as a group name. | |
4155 | To specify a user or group named | |
4156 | .Qq everyone , | |
4157 | use the | |
4158 | .Fl g | |
4159 | or | |
4160 | .Fl u | |
4161 | options. | |
4162 | To specify a group with the same name as a user, use the | |
4163 | .Fl g | |
4164 | options. | |
4165 | .It Xo | |
4166 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4167 | .Ar setname Oc Ns ... | |
4168 | .Xc | |
4169 | The permissions to delegate. | |
4170 | Multiple permissions may be specified as a comma-separated list. | |
4171 | Permission names are the same as ZFS subcommand and property names. | |
4172 | See the property list below. | |
4173 | Property set names, which begin with | |
4174 | .Sy @ , | |
4175 | may be specified. | |
4176 | See the | |
4177 | .Fl s | |
4178 | form below for details. | |
4179 | .El | |
4180 | .Pp | |
4181 | If neither of the | |
4182 | .Fl dl | |
4183 | options are specified, or both are, then the permissions are allowed for the | |
4184 | file system or volume, and all of its descendents. | |
4185 | .Pp | |
4186 | Permissions are generally the ability to use a ZFS subcommand or change a ZFS | |
4187 | property. | |
4188 | The following permissions are available: | |
4189 | .Bd -literal | |
058ac9ba | 4190 | NAME TYPE NOTES |
44f09cdc BB |
4191 | allow subcommand Must also have the permission that is |
4192 | being allowed | |
4193 | clone subcommand Must also have the 'create' ability and | |
4194 | 'mount' ability in the origin file system | |
8750edf1 RL |
4195 | create subcommand Must also have the 'mount' ability. |
4196 | Must also have the 'refreservation' ability to | |
4197 | create a non-sparse volume. | |
058ac9ba | 4198 | destroy subcommand Must also have the 'mount' ability |
0677cb6f | 4199 | diff subcommand Allows lookup of paths within a dataset |
44f09cdc BB |
4200 | given an object number, and the ability |
4201 | to create snapshots necessary to | |
4202 | 'zfs diff'. | |
b5256303 TC |
4203 | load-key subcommand Allows loading and unloading of encryption key |
4204 | (see 'zfs load-key' and 'zfs unload-key'). | |
4205 | change-key subcommand Allows changing an encryption key via | |
4206 | 'zfs change-key'. | |
058ac9ba | 4207 | mount subcommand Allows mount/umount of ZFS datasets |
44f09cdc BB |
4208 | promote subcommand Must also have the 'mount' and 'promote' |
4209 | ability in the origin file system | |
4210 | receive subcommand Must also have the 'mount' and 'create' | |
4211 | ability | |
058ac9ba BB |
4212 | rename subcommand Must also have the 'mount' and 'create' |
4213 | ability in the new parent | |
4214 | rollback subcommand Must also have the 'mount' ability | |
6b4e21c6 | 4215 | send subcommand |
44f09cdc BB |
4216 | share subcommand Allows sharing file systems over NFS |
4217 | or SMB protocols | |
058ac9ba | 4218 | snapshot subcommand Must also have the 'mount' ability |
44f09cdc BB |
4219 | |
4220 | groupquota other Allows accessing any groupquota@... | |
4221 | property | |
058ac9ba BB |
4222 | groupused other Allows reading any groupused@... property |
4223 | userprop other Allows changing any user property | |
44f09cdc BB |
4224 | userquota other Allows accessing any userquota@... |
4225 | property | |
058ac9ba | 4226 | userused other Allows reading any userused@... property |
9c5167d1 NF |
4227 | projectobjquota other Allows accessing any projectobjquota@... |
4228 | property | |
4229 | projectquota other Allows accessing any projectquota@... property | |
4230 | projectobjused other Allows reading any projectobjused@... property | |
4231 | projectused other Allows reading any projectused@... property | |
058ac9ba | 4232 | |
6b4e21c6 | 4233 | aclinherit property |
44f09cdc | 4234 | acltype property |
6b4e21c6 NB |
4235 | atime property |
4236 | canmount property | |
4237 | casesensitivity property | |
4238 | checksum property | |
4239 | compression property | |
4240 | copies property | |
6b4e21c6 NB |
4241 | devices property |
4242 | exec property | |
788eb90c | 4243 | filesystem_limit property |
6b4e21c6 NB |
4244 | mountpoint property |
4245 | nbmand property | |
4246 | normalization property | |
4247 | primarycache property | |
4248 | quota property | |
4249 | readonly property | |
4250 | recordsize property | |
4251 | refquota property | |
4252 | refreservation property | |
4253 | reservation property | |
4254 | secondarycache property | |
4255 | setuid property | |
4256 | sharenfs property | |
4257 | sharesmb property | |
4258 | snapdir property | |
788eb90c | 4259 | snapshot_limit property |
6b4e21c6 NB |
4260 | utf8only property |
4261 | version property | |
4262 | volblocksize property | |
4263 | volsize property | |
4264 | vscan property | |
4265 | xattr property | |
4266 | zoned property | |
44f09cdc BB |
4267 | .Ed |
4268 | .It Xo | |
4269 | .Nm | |
4270 | .Cm allow | |
4271 | .Fl c | |
4272 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4273 | .Ar setname Oc Ns ... | |
4274 | .Ar filesystem Ns | Ns Ar volume | |
4275 | .Xc | |
4276 | Sets | |
4277 | .Qq create time | |
4278 | permissions. | |
4279 | These permissions are granted | |
4280 | .Pq locally | |
4281 | to the creator of any newly-created descendent file system. | |
4282 | .It Xo | |
4283 | .Nm | |
4284 | .Cm allow | |
4285 | .Fl s No @ Ns Ar setname | |
4286 | .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4287 | .Ar setname Oc Ns ... | |
4288 | .Ar filesystem Ns | Ns Ar volume | |
4289 | .Xc | |
4290 | Defines or adds permissions to a permission set. | |
4291 | The set can be used by other | |
4292 | .Nm zfs Cm allow | |
4293 | commands for the specified file system and its descendents. | |
4294 | Sets are evaluated dynamically, so changes to a set are immediately reflected. | |
4295 | Permission sets follow the same naming restrictions as ZFS file systems, but the | |
4296 | name must begin with | |
4297 | .Sy @ , | |
4298 | and can be no more than 64 characters long. | |
4299 | .It Xo | |
4300 | .Nm | |
4301 | .Cm unallow | |
4302 | .Op Fl dglru | |
4303 | .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns ... | |
4304 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4305 | .Ar setname Oc Ns ... Oc | |
4306 | .Ar filesystem Ns | Ns Ar volume | |
0238a975 | 4307 | .Xc |
4308 | .It Xo | |
44f09cdc BB |
4309 | .Nm |
4310 | .Cm unallow | |
4311 | .Op Fl dlr | |
4312 | .Fl e Ns | Ns Sy everyone | |
4313 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4314 | .Ar setname Oc Ns ... Oc | |
4315 | .Ar filesystem Ns | Ns Ar volume | |
cb110f25 YP |
4316 | .Xc |
4317 | .It Xo | |
44f09cdc BB |
4318 | .Nm |
4319 | .Cm unallow | |
4320 | .Op Fl r | |
4321 | .Fl c | |
4322 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4323 | .Ar setname Oc Ns ... Oc | |
4324 | .Ar filesystem Ns | Ns Ar volume | |
4325 | .Xc | |
4326 | Removes permissions that were granted with the | |
4327 | .Nm zfs Cm allow | |
4328 | command. | |
4329 | No permissions are explicitly denied, so other permissions granted are still in | |
4330 | effect. | |
4331 | For example, if the permission is granted by an ancestor. | |
4332 | If no permissions are specified, then all permissions for the specified | |
4333 | .Ar user , | |
4334 | .Ar group , | |
4335 | or | |
4336 | .Sy everyone | |
4337 | are removed. | |
4338 | Specifying | |
4339 | .Sy everyone | |
4340 | .Po or using the | |
4341 | .Fl e | |
4342 | option | |
4343 | .Pc | |
4344 | only removes the permissions that were granted to everyone, not all permissions | |
4345 | for every user and group. | |
4346 | See the | |
4347 | .Nm zfs Cm allow | |
4348 | command for a description of the | |
4349 | .Fl ldugec | |
4350 | options. | |
4351 | .Bl -tag -width "-r" | |
4352 | .It Fl r | |
058ac9ba | 4353 | Recursively remove the permissions from this file system and all descendents. |
44f09cdc BB |
4354 | .El |
4355 | .It Xo | |
4356 | .Nm | |
4357 | .Cm unallow | |
4358 | .Op Fl r | |
4359 | .Fl s No @ Ns Ar setname | |
4360 | .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns | |
4361 | .Ar setname Oc Ns ... Oc | |
4362 | .Ar filesystem Ns | Ns Ar volume | |
4363 | .Xc | |
4364 | Removes permissions from a permission set. | |
4365 | If no permissions are specified, then all permissions are removed, thus removing | |
4366 | the set entirely. | |
4367 | .It Xo | |
4368 | .Nm | |
4369 | .Cm hold | |
4370 | .Op Fl r | |
4371 | .Ar tag Ar snapshot Ns ... | |
4372 | .Xc | |
4373 | Adds a single reference, named with the | |
4374 | .Ar tag | |
4375 | argument, to the specified snapshot or snapshots. | |
4376 | Each snapshot has its own tag namespace, and tags must be unique within that | |
4377 | space. | |
4378 | .Pp | |
4379 | If a hold exists on a snapshot, attempts to destroy that snapshot by using the | |
4380 | .Nm zfs Cm destroy | |
4381 | command return | |
4382 | .Er EBUSY . | |
4383 | .Bl -tag -width "-r" | |
4384 | .It Fl r | |
4385 | Specifies that a hold with the given tag is applied recursively to the snapshots | |
4386 | of all descendent file systems. | |
4387 | .El | |
4388 | .It Xo | |
4389 | .Nm | |
4390 | .Cm holds | |
a9d6270a | 4391 | .Op Fl rH |
44f09cdc BB |
4392 | .Ar snapshot Ns ... |
4393 | .Xc | |
058ac9ba | 4394 | Lists all existing user references for the given snapshot or snapshots. |
44f09cdc BB |
4395 | .Bl -tag -width "-r" |
4396 | .It Fl r | |
4397 | Lists the holds that are set on the named descendent snapshots, in addition to | |
4398 | listing the holds on the named snapshot. | |
a9d6270a | 4399 | .It Fl H |
4400 | Do not print headers, use tab-delimited output. | |
44f09cdc BB |
4401 | .El |
4402 | .It Xo | |
4403 | .Nm | |
4404 | .Cm release | |
4405 | .Op Fl r | |
4406 | .Ar tag Ar snapshot Ns ... | |
4407 | .Xc | |
4408 | Removes a single reference, named with the | |
4409 | .Ar tag | |
4410 | argument, from the specified snapshot or snapshots. | |
4411 | The tag must already exist for each snapshot. | |
4412 | If a hold exists on a snapshot, attempts to destroy that snapshot by using the | |
4413 | .Nm zfs Cm destroy | |
4414 | command return | |
4415 | .Er EBUSY . | |
4416 | .Bl -tag -width "-r" | |
4417 | .It Fl r | |
4418 | Recursively releases a hold with the given tag on the snapshots of all | |
4419 | descendent file systems. | |
4420 | .El | |
4421 | .It Xo | |
4422 | .Nm | |
4423 | .Cm diff | |
4424 | .Op Fl FHt | |
4425 | .Ar snapshot Ar snapshot Ns | Ns Ar filesystem | |
4426 | .Xc | |
0677cb6f RL |
4427 | Display the difference between a snapshot of a given filesystem and another |
4428 | snapshot of that filesystem from a later time or the current contents of the | |
44f09cdc BB |
4429 | filesystem. |
4430 | The first column is a character indicating the type of change, the other columns | |
4431 | indicate pathname, new pathname | |
4432 | .Pq in case of rename , | |
4433 | change in link count, and optionally file type and/or change time. | |
0677cb6f | 4434 | The types of change are: |
44f09cdc | 4435 | .Bd -literal |
0677cb6f RL |
4436 | - The path has been removed |
4437 | + The path has been created | |
4438 | M The path has been modified | |
4439 | R The path has been renamed | |
44f09cdc BB |
4440 | .Ed |
4441 | .Bl -tag -width "-F" | |
4442 | .It Fl F | |
4443 | Display an indication of the type of file, in a manner similar to the | |
4444 | .Fl | |
4445 | option of | |
4446 | .Xr ls 1 . | |
4447 | .Bd -literal | |
0677cb6f RL |
4448 | B Block device |
4449 | C Character device | |
4450 | / Directory | |
4451 | > Door | |
4452 | | Named pipe | |
4453 | @ Symbolic link | |
4454 | P Event port | |
4455 | = Socket | |
4456 | F Regular file | |
44f09cdc BB |
4457 | .Ed |
4458 | .It Fl H | |
4459 | Give more parsable tab-separated output, without header lines and without | |
4460 | arrows. | |
4461 | .It Fl t | |
0677cb6f | 4462 | Display the path's inode change time as the first column of output. |
44f09cdc | 4463 | .El |
b5256303 TC |
4464 | .It Xo |
4465 | .Nm | |
d99a0153 | 4466 | .Cm program |
272b5d73 | 4467 | .Op Fl jn |
c568ab8d MA |
4468 | .Op Fl t Ar instruction-limit |
4469 | .Op Fl m Ar memory-limit | |
d99a0153 CW |
4470 | .Ar pool script |
4471 | .Op Ar arg1 No ... | |
4472 | .Xc | |
4473 | Executes | |
4474 | .Ar script | |
4475 | as a ZFS channel program on | |
4476 | .Ar pool . | |
4477 | The ZFS channel | |
4478 | program interface allows ZFS administrative operations to be run | |
4479 | programmatically via a Lua script. | |
4480 | The entire script is executed atomically, with no other administrative | |
4481 | operations taking effect concurrently. | |
4482 | A library of ZFS calls is made available to channel program scripts. | |
4483 | Channel programs may only be run with root privileges. | |
4484 | .sp | |
4485 | For full documentation of the ZFS channel program interface, see the manual | |
4486 | page for | |
4487 | .Xr zfs-program 8 . | |
4488 | .Bl -tag -width "" | |
272b5d73 AP |
4489 | .It Fl j |
4490 | Display channel program output in JSON format. When this flag is specified and | |
4491 | standard output is empty - channel program encountered an error. The details of | |
4492 | such an error will be printed to standard error in plain text. | |
5b72a38d SD |
4493 | .It Fl n |
4494 | Executes a read-only channel program, which runs faster. | |
4495 | The program cannot change on-disk state by calling functions from | |
4496 | the zfs.sync submodule. | |
4497 | The program can be used to gather information such as properties and | |
4498 | determining if changes would succeed (zfs.check.*). | |
4499 | Without this flag, all pending changes must be synced to disk before | |
4500 | a channel program can complete. | |
c568ab8d MA |
4501 | .It Fl t Ar instruction-limit |
4502 | Limit the number of Lua instructions to execute. | |
4503 | If a channel program executes more than the specified number of instructions, | |
4504 | it will be stopped and an error will be returned. | |
4505 | The default limit is 10 million instructions, and it can be set to a maximum of | |
4506 | 100 million instructions. | |
d99a0153 CW |
4507 | .It Fl m Ar memory-limit |
4508 | Memory limit, in bytes. | |
4509 | If a channel program attempts to allocate more memory than the given limit, | |
4510 | it will be stopped and an error returned. | |
4511 | The default memory limit is 10 MB, and can be set to a maximum of 100 MB. | |
4512 | .sp | |
4513 | All remaining argument strings are passed directly to the channel program as | |
4514 | arguments. | |
4515 | See | |
4516 | .Xr zfs-program 8 | |
4517 | for more information. | |
4518 | .El | |
4519 | .It Xo | |
4520 | .Nm | |
b5256303 TC |
4521 | .Cm load-key |
4522 | .Op Fl nr | |
4523 | .Op Fl L Ar keylocation | |
4524 | .Fl a | Ar filesystem | |
4525 | .Xc | |
4526 | Load the key for | |
4527 | .Ar filesystem , | |
4528 | allowing it and all children that inherit the | |
4529 | .Sy keylocation | |
4530 | property to be accessed. The key will be expected in the format specified by the | |
4531 | .Sy keyformat | |
4532 | and location specified by the | |
4533 | .Sy keylocation | |
4534 | property. Note that if the | |
4535 | .Sy keylocation | |
4536 | is set to | |
4537 | .Sy prompt | |
4538 | the terminal will interactively wait for the key to be entered. Loading a key | |
4539 | will not automatically mount the dataset. If that functionality is desired, | |
4540 | .Nm zfs Cm mount Sy -l | |
4541 | will ask for the key and mount the dataset. Once the key is loaded the | |
4542 | .Sy keystatus | |
4543 | property will become | |
4544 | .Sy available . | |
4545 | .Bl -tag -width "-r" | |
4546 | .It Fl r | |
4547 | Recursively loads the keys for the specified filesystem and all descendent | |
4548 | encryption roots. | |
4549 | .It Fl a | |
4550 | Loads the keys for all encryption roots in all imported pools. | |
4551 | .It Fl n | |
4552 | Do a dry-run | |
4553 | .Pq Qq No-op | |
4554 | load-key. This will cause zfs to simply check that the | |
4555 | provided key is correct. This command may be run even if the key is already | |
4556 | loaded. | |
4557 | .It Fl L Ar keylocation | |
4558 | Use | |
4559 | .Ar keylocation | |
4560 | instead of the | |
4561 | .Sy keylocation | |
4562 | property. This will not change the value of the property on the dataset. Note | |
4563 | that if used with either | |
4564 | .Fl r | |
4565 | or | |
4566 | .Fl a , | |
4567 | .Ar keylocation | |
4568 | may only be given as | |
4569 | .Sy prompt . | |
4570 | .El | |
4571 | .It Xo | |
4572 | .Nm | |
4573 | .Cm unload-key | |
4574 | .Op Fl r | |
4575 | .Fl a | Ar filesystem | |
4576 | .Xc | |
4577 | Unloads a key from ZFS, removing the ability to access the dataset and all of | |
4578 | its children that inherit the | |
4579 | .Sy keylocation | |
4580 | property. This requires that the dataset is not currently open or mounted. Once | |
4581 | the key is unloaded the | |
4582 | .Sy keystatus | |
4583 | property will become | |
4584 | .Sy unavailable . | |
4585 | .Bl -tag -width "-r" | |
4586 | .It Fl r | |
4587 | Recursively unloads the keys for the specified filesystem and all descendent | |
4588 | encryption roots. | |
4589 | .It Fl a | |
4590 | Unloads the keys for all encryption roots in all imported pools. | |
4591 | .El | |
4592 | .It Xo | |
4593 | .Nm | |
4594 | .Cm change-key | |
4595 | .Op Fl l | |
4596 | .Op Fl o Ar keylocation Ns = Ns Ar value | |
4597 | .Op Fl o Ar keyformat Ns = Ns Ar value | |
4598 | .Op Fl o Ar pbkdf2iters Ns = Ns Ar value | |
4599 | .Ar filesystem | |
4600 | .Xc | |
4601 | .It Xo | |
4602 | .Nm | |
4603 | .Cm change-key | |
4604 | .Fl i | |
4605 | .Op Fl l | |
4606 | .Ar filesystem | |
4607 | .Xc | |
4608 | Allows a user to change the encryption key used to access a dataset. This | |
4609 | command requires that the existing key for the dataset is already loaded into | |
4610 | ZFS. This command may also be used to change the | |
4611 | .Sy keylocation , | |
4612 | .Sy keyformat , | |
4613 | and | |
4614 | .Sy pbkdf2iters | |
4615 | properties as needed. If the dataset was not previously an encryption root it | |
4616 | will become one. Alternatively, the | |
4617 | .Fl i | |
4618 | flag may be provided to cause an encryption root to inherit the parent's key | |
4619 | instead. | |
4620 | .Bl -tag -width "-r" | |
4621 | .It Fl l | |
4622 | Ensures the key is loaded before attempting to change the key. This is | |
4623 | effectively equivalent to | |
4624 | .Qq Nm zfs Cm load-key Ar filesystem ; Nm zfs Cm change-key Ar filesystem | |
4625 | .It Fl o Ar property Ns = Ns Ar value | |
4626 | Allows the user to set encryption key properties ( | |
4627 | .Sy keyformat , | |
4628 | .Sy keylocation , | |
4629 | and | |
4630 | .Sy pbkdf2iters | |
4631 | ) while changing the key. This is the only way to alter | |
4632 | .Sy keyformat | |
4633 | and | |
4634 | .Sy pbkdf2iters | |
4635 | after the dataset has been created. | |
4636 | .It Fl i | |
4637 | Indicates that zfs should make | |
4638 | .Ar filesystem | |
4639 | inherit the key of its parent. Note that this command can only be run on an | |
4640 | encryption root that has an encrypted parent. | |
4641 | .El | |
50478c6d T |
4642 | .It Xo |
4643 | .Nm | |
4644 | .Cm version | |
4645 | .Xc | |
4646 | Displays the software version of the | |
4647 | .Nm | |
4648 | userland utility and the zfs kernel module. | |
44f09cdc BB |
4649 | .El |
4650 | .Sh EXIT STATUS | |
4651 | The | |
4652 | .Nm | |
4653 | utility exits 0 on success, 1 if an error occurs, and 2 if invalid command line | |
4654 | options were specified. | |
4655 | .Sh EXAMPLES | |
4656 | .Bl -tag -width "" | |
4657 | .It Sy Example 1 No Creating a ZFS File System Hierarchy | |
4658 | The following commands create a file system named | |
4659 | .Em pool/home | |
4660 | and a file system named | |
4661 | .Em pool/home/bob . | |
4662 | The mount point | |
4663 | .Pa /export/home | |
4664 | is set for the parent file system, and is automatically inherited by the child | |
4665 | file system. | |
4666 | .Bd -literal | |
4667 | # zfs create pool/home | |
4668 | # zfs set mountpoint=/export/home pool/home | |
4669 | # zfs create pool/home/bob | |
4670 | .Ed | |
4671 | .It Sy Example 2 No Creating a ZFS Snapshot | |
4672 | The following command creates a snapshot named | |
4673 | .Sy yesterday . | |
4674 | This snapshot is mounted on demand in the | |
4675 | .Pa .zfs/snapshot | |
4676 | directory at the root of the | |
4677 | .Em pool/home/bob | |
4678 | file system. | |
4679 | .Bd -literal | |
4680 | # zfs snapshot pool/home/bob@yesterday | |
4681 | .Ed | |
4682 | .It Sy Example 3 No Creating and Destroying Multiple Snapshots | |
4683 | The following command creates snapshots named | |
4684 | .Sy yesterday | |
4685 | of | |
4686 | .Em pool/home | |
4687 | and all of its descendent file systems. | |
4688 | Each snapshot is mounted on demand in the | |
4689 | .Pa .zfs/snapshot | |
4690 | directory at the root of its file system. | |
4691 | The second command destroys the newly created snapshots. | |
4692 | .Bd -literal | |
4693 | # zfs snapshot -r pool/home@yesterday | |
4694 | # zfs destroy -r pool/home@yesterday | |
4695 | .Ed | |
4696 | .It Sy Example 4 No Disabling and Enabling File System Compression | |
4697 | The following command disables the | |
4698 | .Sy compression | |
4699 | property for all file systems under | |
4700 | .Em pool/home . | |
4701 | The next command explicitly enables | |
4702 | .Sy compression | |
4703 | for | |
4704 | .Em pool/home/anne . | |
4705 | .Bd -literal | |
4706 | # zfs set compression=off pool/home | |
4707 | # zfs set compression=on pool/home/anne | |
4708 | .Ed | |
4709 | .It Sy Example 5 No Listing ZFS Datasets | |
4710 | The following command lists all active file systems and volumes in the system. | |
4711 | Snapshots are displayed if the | |
4712 | .Sy listsnaps | |
4713 | property is | |
4714 | .Sy on . | |
4715 | The default is | |
4716 | .Sy off . | |
4717 | See | |
4718 | .Xr zpool 8 | |
4719 | for more information on pool properties. | |
4720 | .Bd -literal | |
4721 | # zfs list | |
4722 | NAME USED AVAIL REFER MOUNTPOINT | |
4723 | pool 450K 457G 18K /pool | |
4724 | pool/home 315K 457G 21K /export/home | |
4725 | pool/home/anne 18K 457G 18K /export/home/anne | |
4726 | pool/home/bob 276K 457G 276K /export/home/bob | |
4727 | .Ed | |
4728 | .It Sy Example 6 No Setting a Quota on a ZFS File System | |
4729 | The following command sets a quota of 50 Gbytes for | |
4730 | .Em pool/home/bob . | |
4731 | .Bd -literal | |
4732 | # zfs set quota=50G pool/home/bob | |
4733 | .Ed | |
4734 | .It Sy Example 7 No Listing ZFS Properties | |
4735 | The following command lists all properties for | |
4736 | .Em pool/home/bob . | |
4737 | .Bd -literal | |
4738 | # zfs get all pool/home/bob | |
058ac9ba BB |
4739 | NAME PROPERTY VALUE SOURCE |
4740 | pool/home/bob type filesystem - | |
4741 | pool/home/bob creation Tue Jul 21 15:53 2009 - | |
4742 | pool/home/bob used 21K - | |
4743 | pool/home/bob available 20.0G - | |
4744 | pool/home/bob referenced 21K - | |
4745 | pool/home/bob compressratio 1.00x - | |
4746 | pool/home/bob mounted yes - | |
4747 | pool/home/bob quota 20G local | |
4748 | pool/home/bob reservation none default | |
4749 | pool/home/bob recordsize 128K default | |
4750 | pool/home/bob mountpoint /pool/home/bob default | |
4751 | pool/home/bob sharenfs off default | |
4752 | pool/home/bob checksum on default | |
4753 | pool/home/bob compression on local | |
4754 | pool/home/bob atime on default | |
4755 | pool/home/bob devices on default | |
4756 | pool/home/bob exec on default | |
4757 | pool/home/bob setuid on default | |
4758 | pool/home/bob readonly off default | |
4759 | pool/home/bob zoned off default | |
4760 | pool/home/bob snapdir hidden default | |
023699cd | 4761 | pool/home/bob acltype off default |
058ac9ba BB |
4762 | pool/home/bob aclinherit restricted default |
4763 | pool/home/bob canmount on default | |
058ac9ba BB |
4764 | pool/home/bob xattr on default |
4765 | pool/home/bob copies 1 default | |
4766 | pool/home/bob version 4 - | |
4767 | pool/home/bob utf8only off - | |
4768 | pool/home/bob normalization none - | |
4769 | pool/home/bob casesensitivity sensitive - | |
4770 | pool/home/bob vscan off default | |
4771 | pool/home/bob nbmand off default | |
4772 | pool/home/bob sharesmb off default | |
4773 | pool/home/bob refquota none default | |
4774 | pool/home/bob refreservation none default | |
4775 | pool/home/bob primarycache all default | |
4776 | pool/home/bob secondarycache all default | |
4777 | pool/home/bob usedbysnapshots 0 - | |
4778 | pool/home/bob usedbydataset 21K - | |
4779 | pool/home/bob usedbychildren 0 - | |
4780 | pool/home/bob usedbyrefreservation 0 - | |
44f09cdc BB |
4781 | .Ed |
4782 | .Pp | |
058ac9ba | 4783 | The following command gets a single property value. |
44f09cdc BB |
4784 | .Bd -literal |
4785 | # zfs get -H -o value compression pool/home/bob | |
058ac9ba | 4786 | on |
44f09cdc BB |
4787 | .Ed |
4788 | The following command lists all properties with local settings for | |
4789 | .Em pool/home/bob . | |
4790 | .Bd -literal | |
4791 | # zfs get -r -s local -o name,property,value all pool/home/bob | |
058ac9ba BB |
4792 | NAME PROPERTY VALUE |
4793 | pool/home/bob quota 20G | |
4794 | pool/home/bob compression on | |
44f09cdc BB |
4795 | .Ed |
4796 | .It Sy Example 8 No Rolling Back a ZFS File System | |
4797 | The following command reverts the contents of | |
4798 | .Em pool/home/anne | |
4799 | to the snapshot named | |
4800 | .Sy yesterday , | |
4801 | deleting all intermediate snapshots. | |
4802 | .Bd -literal | |
4803 | # zfs rollback -r pool/home/anne@yesterday | |
4804 | .Ed | |
4805 | .It Sy Example 9 No Creating a ZFS Clone | |
4806 | The following command creates a writable file system whose initial contents are | |
4807 | the same as | |
4808 | .Em pool/home/bob@yesterday . | |
4809 | .Bd -literal | |
4810 | # zfs clone pool/home/bob@yesterday pool/clone | |
4811 | .Ed | |
4812 | .It Sy Example 10 No Promoting a ZFS Clone | |
4813 | The following commands illustrate how to test out changes to a file system, and | |
4814 | then replace the original file system with the changed one, using clones, clone | |
4815 | promotion, and renaming: | |
4816 | .Bd -literal | |
4817 | # zfs create pool/project/production | |
058ac9ba | 4818 | populate /pool/project/production with data |
44f09cdc BB |
4819 | # zfs snapshot pool/project/production@today |
4820 | # zfs clone pool/project/production@today pool/project/beta | |
4821 | make changes to /pool/project/beta and test them | |
4822 | # zfs promote pool/project/beta | |
4823 | # zfs rename pool/project/production pool/project/legacy | |
4824 | # zfs rename pool/project/beta pool/project/production | |
4825 | once the legacy version is no longer needed, it can be destroyed | |
4826 | # zfs destroy pool/project/legacy | |
4827 | .Ed | |
4828 | .It Sy Example 11 No Inheriting ZFS Properties | |
4829 | The following command causes | |
4830 | .Em pool/home/bob | |
4831 | and | |
4832 | .Em pool/home/anne | |
4833 | to inherit the | |
4834 | .Sy checksum | |
4835 | property from their parent. | |
4836 | .Bd -literal | |
4837 | # zfs inherit checksum pool/home/bob pool/home/anne | |
4838 | .Ed | |
4839 | .It Sy Example 12 No Remotely Replicating ZFS Data | |
4840 | The following commands send a full stream and then an incremental stream to a | |
4841 | remote machine, restoring them into | |
4842 | .Em poolB/received/fs@a | |
4843 | and | |
4844 | .Em poolB/received/fs@b , | |
4845 | respectively. | |
4846 | .Em poolB | |
4847 | must contain the file system | |
4848 | .Em poolB/received , | |
4849 | and must not initially contain | |
4850 | .Em poolB/received/fs . | |
4851 | .Bd -literal | |
4852 | # zfs send pool/fs@a | \e | |
4853 | ssh host zfs receive poolB/received/fs@a | |
4854 | # zfs send -i a pool/fs@b | \e | |
4855 | ssh host zfs receive poolB/received/fs | |
4856 | .Ed | |
4857 | .It Sy Example 13 No Using the zfs receive -d Option | |
4858 | The following command sends a full stream of | |
4859 | .Em poolA/fsA/fsB@snap | |
4860 | to a remote machine, receiving it into | |
4861 | .Em poolB/received/fsA/fsB@snap . | |
4862 | The | |
4863 | .Em fsA/fsB@snap | |
4864 | portion of the received snapshot's name is determined from the name of the sent | |
4865 | snapshot. | |
4866 | .Em poolB | |
4867 | must contain the file system | |
4868 | .Em poolB/received . | |
4869 | If | |
4870 | .Em poolB/received/fsA | |
4871 | does not exist, it is created as an empty file system. | |
4872 | .Bd -literal | |
4873 | # zfs send poolA/fsA/fsB@snap | \e | |
4874 | ssh host zfs receive -d poolB/received | |
4875 | .Ed | |
4876 | .It Sy Example 14 No Setting User Properties | |
4877 | The following example sets the user-defined | |
4878 | .Sy com.example:department | |
4879 | property for a dataset. | |
4880 | .Bd -literal | |
4881 | # zfs set com.example:department=12345 tank/accounting | |
4882 | .Ed | |
4883 | .It Sy Example 15 No Performing a Rolling Snapshot | |
4884 | The following example shows how to maintain a history of snapshots with a | |
4885 | consistent naming scheme. | |
4886 | To keep a week's worth of snapshots, the user destroys the oldest snapshot, | |
4887 | renames the remaining snapshots, and then creates a new snapshot, as follows: | |
4888 | .Bd -literal | |
4889 | # zfs destroy -r pool/users@7daysago | |
4890 | # zfs rename -r pool/users@6daysago @7daysago | |
4891 | # zfs rename -r pool/users@5daysago @6daysago | |
22448f08 BG |
4892 | # zfs rename -r pool/users@4daysago @5daysago |
4893 | # zfs rename -r pool/users@3daysago @4daysago | |
4894 | # zfs rename -r pool/users@2daysago @3daysago | |
44f09cdc BB |
4895 | # zfs rename -r pool/users@yesterday @2daysago |
4896 | # zfs rename -r pool/users@today @yesterday | |
4897 | # zfs snapshot -r pool/users@today | |
4898 | .Ed | |
4899 | .It Sy Example 16 No Setting sharenfs Property Options on a ZFS File System | |
4900 | The following commands show how to set | |
4901 | .Sy sharenfs | |
4902 | property options to enable | |
4903 | .Sy rw | |
4904 | access for a set of | |
4905 | .Sy IP | |
4906 | addresses and to enable root access for system | |
4907 | .Sy neo | |
4908 | on the | |
4909 | .Em tank/home | |
4910 | file system. | |
4911 | .Bd -literal | |
4912 | # zfs set sharenfs='rw=@123.123.0.0/16,root=neo' tank/home | |
4913 | .Ed | |
4914 | .Pp | |
4915 | If you are using | |
4916 | .Sy DNS | |
4917 | for host name resolution, specify the fully qualified hostname. | |
4918 | .It Sy Example 17 No Delegating ZFS Administration Permissions on a ZFS Dataset | |
4919 | The following example shows how to set permissions so that user | |
4920 | .Sy cindys | |
4921 | can create, destroy, mount, and take snapshots on | |
4922 | .Em tank/cindys . | |
4923 | The permissions on | |
4924 | .Em tank/cindys | |
4925 | are also displayed. | |
4926 | .Bd -literal | |
4927 | # zfs allow cindys create,destroy,mount,snapshot tank/cindys | |
4928 | # zfs allow tank/cindys | |
4929 | ---- Permissions on tank/cindys -------------------------------------- | |
4930 | Local+Descendent permissions: | |
4931 | user cindys create,destroy,mount,snapshot | |
4932 | .Ed | |
4933 | .Pp | |
4934 | Because the | |
4935 | .Em tank/cindys | |
4936 | mount point permission is set to 755 by default, user | |
4937 | .Sy cindys | |
4938 | will be unable to mount file systems under | |
4939 | .Em tank/cindys . | |
4940 | Add an ACE similar to the following syntax to provide mount point access: | |
4941 | .Bd -literal | |
4942 | # chmod A+user:cindys:add_subdirectory:allow /tank/cindys | |
4943 | .Ed | |
4944 | .It Sy Example 18 No Delegating Create Time Permissions on a ZFS Dataset | |
4945 | The following example shows how to grant anyone in the group | |
4946 | .Sy staff | |
4947 | to create file systems in | |
4948 | .Em tank/users . | |
4949 | This syntax also allows staff members to destroy their own file systems, but not | |
4950 | destroy anyone else's file system. | |
4951 | The permissions on | |
4952 | .Em tank/users | |
4953 | are also displayed. | |
4954 | .Bd -literal | |
4955 | # zfs allow staff create,mount tank/users | |
4956 | # zfs allow -c destroy tank/users | |
4957 | # zfs allow tank/users | |
4958 | ---- Permissions on tank/users --------------------------------------- | |
4959 | Permission sets: | |
4960 | destroy | |
4961 | Local+Descendent permissions: | |
4962 | group staff create,mount | |
4963 | .Ed | |
4964 | .It Sy Example 19 No Defining and Granting a Permission Set on a ZFS Dataset | |
4965 | The following example shows how to define and grant a permission set on the | |
4966 | .Em tank/users | |
4967 | file system. | |
4968 | The permissions on | |
4969 | .Em tank/users | |
4970 | are also displayed. | |
4971 | .Bd -literal | |
4972 | # zfs allow -s @pset create,destroy,snapshot,mount tank/users | |
4973 | # zfs allow staff @pset tank/users | |
4974 | # zfs allow tank/users | |
4975 | ---- Permissions on tank/users --------------------------------------- | |
4976 | Permission sets: | |
058ac9ba | 4977 | @pset create,destroy,mount,snapshot |
44f09cdc BB |
4978 | Local+Descendent permissions: |
4979 | group staff @pset | |
4980 | .Ed | |
4981 | .It Sy Example 20 No Delegating Property Permissions on a ZFS Dataset | |
4982 | The following example shows to grant the ability to set quotas and reservations | |
4983 | on the | |
4984 | .Em users/home | |
4985 | file system. | |
4986 | The permissions on | |
4987 | .Em users/home | |
4988 | are also displayed. | |
4989 | .Bd -literal | |
4990 | # zfs allow cindys quota,reservation users/home | |
4991 | # zfs allow users/home | |
4992 | ---- Permissions on users/home --------------------------------------- | |
4993 | Local+Descendent permissions: | |
058ac9ba | 4994 | user cindys quota,reservation |
44f09cdc BB |
4995 | cindys% zfs set quota=10G users/home/marks |
4996 | cindys% zfs get quota users/home/marks | |
4997 | NAME PROPERTY VALUE SOURCE | |
4998 | users/home/marks quota 10G local | |
4999 | .Ed | |
5000 | .It Sy Example 21 No Removing ZFS Delegated Permissions on a ZFS Dataset | |
5001 | The following example shows how to remove the snapshot permission from the | |
5002 | .Sy staff | |
5003 | group on the | |
5004 | .Em tank/users | |
5005 | file system. | |
5006 | The permissions on | |
5007 | .Em tank/users | |
5008 | are also displayed. | |
5009 | .Bd -literal | |
5010 | # zfs unallow staff snapshot tank/users | |
5011 | # zfs allow tank/users | |
5012 | ---- Permissions on tank/users --------------------------------------- | |
5013 | Permission sets: | |
058ac9ba | 5014 | @pset create,destroy,mount,snapshot |
44f09cdc BB |
5015 | Local+Descendent permissions: |
5016 | group staff @pset | |
5017 | .Ed | |
5018 | .It Sy Example 22 No Showing the differences between a snapshot and a ZFS Dataset | |
0677cb6f | 5019 | The following example shows how to see what has changed between a prior |
44f09cdc BB |
5020 | snapshot of a ZFS dataset and its current state. |
5021 | The | |
5022 | .Fl F | |
5023 | option is used to indicate type information for the files affected. | |
5024 | .Bd -literal | |
0677cb6f RL |
5025 | # zfs diff -F tank/test@before tank/test |
5026 | M / /tank/test/ | |
5027 | M F /tank/test/linked (+1) | |
5028 | R F /tank/test/oldname -> /tank/test/newname | |
5029 | - F /tank/test/deleted | |
5030 | + F /tank/test/created | |
5031 | M F /tank/test/modified | |
44f09cdc BB |
5032 | .Ed |
5033 | .It Sy Example 23 No Creating a bookmark | |
5034 | The following example create a bookmark to a snapshot. This bookmark | |
5035 | can then be used instead of snapshot in send streams. | |
5036 | .Bd -literal | |
a215ee16 | 5037 | # zfs bookmark rpool@snapshot rpool#bookmark |
44f09cdc BB |
5038 | .Ed |
5039 | .It Sy Example 24 No Setting sharesmb Property Options on a ZFS File System | |
5040 | The following example show how to share SMB filesystem through ZFS. Note that | |
5041 | that a user and his/her password must be given. | |
5042 | .Bd -literal | |
5043 | # smbmount //127.0.0.1/share_tmp /mnt/tmp \\ | |
5044 | -o user=workgroup/turbo,password=obrut,uid=1000 | |
5045 | .Ed | |
5046 | .Pp | |
5047 | Minimal | |
5048 | .Em /etc/samba/smb.conf | |
5049 | configuration required: | |
5050 | .Pp | |
5051 | Samba will need to listen to 'localhost' (127.0.0.1) for the ZFS utilities to | |
5052 | communicate with Samba. This is the default behavior for most Linux | |
5053 | distributions. | |
5054 | .Pp | |
5055 | Samba must be able to authenticate a user. This can be done in a number of | |
5056 | ways, depending on if using the system password file, LDAP or the Samba | |
5057 | specific smbpasswd file. How to do this is outside the scope of this manual. | |
5058 | Please refer to the | |
5059 | .Xr smb.conf 5 | |
5060 | man page for more information. | |
5061 | .Pp | |
5062 | See the | |
5063 | .Sy USERSHARE section | |
5064 | of the | |
5065 | .Xr smb.conf 5 | |
5066 | man page for all configuration options in case you need to modify any options | |
5067 | to the share afterwards. Do note that any changes done with the | |
5068 | .Xr net 8 | |
5069 | command will be undone if the share is ever unshared (such as at a reboot etc). | |
5070 | .El | |
5071 | .Sh INTERFACE STABILITY | |
5072 | .Sy Committed . | |
5073 | .Sh SEE ALSO | |
90cdf283 | 5074 | .Xr attr 1 , |
44f09cdc BB |
5075 | .Xr gzip 1 , |
5076 | .Xr ssh 1 , | |
44f09cdc | 5077 | .Xr chmod 2 , |
90cdf283 | 5078 | .Xr fsync 2 , |
44f09cdc BB |
5079 | .Xr stat 2 , |
5080 | .Xr write 2 , | |
44f09cdc | 5081 | .Xr acl 5 , |
90cdf283 | 5082 | .Xr attributes 5 , |
44f09cdc BB |
5083 | .Xr exports 5 , |
5084 | .Xr exportfs 8 , | |
90cdf283 | 5085 | .Xr mount 8 , |
44f09cdc | 5086 | .Xr net 8 , |
90cdf283 | 5087 | .Xr selinux 8 , |
5088 | .Xr zpool 8 |