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