logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zfs.8 (27682B)

    

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