man/man8/zfs-allow.8

   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) 2013 by Saso Kiselkov. All rights reserved.
  25 .\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
  26 .\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
  27 .\" Copyright (c) 2014 Integros [integros.com]
  28 .\" Copyright 2019 Richard Laager. All rights reserved.
  29 .\" Copyright 2018 Nexenta Systems, Inc.
  30 .\" Copyright 2019 Joyent, Inc.
  31 .\"
  32 .Dd March 16, 2022
  33 .Dt ZFS-ALLOW 8
  34 .Os
  35 .
  36 .Sh NAME
  37 .Nm zfs-allow
  38 .Nd delegate ZFS administration permissions to unprivileged users
  39 .Sh SYNOPSIS
  40 .Nm zfs
  41 .Cm allow
  42 .Op Fl dglu
  43 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns …
  44 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  45 .Ar setname Oc Ns …
  46 .Ar filesystem Ns | Ns Ar volume
  47 .Nm zfs
  48 .Cm allow
  49 .Op Fl dl
  50 .Fl e Ns | Ns Sy everyone
  51 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  52 .Ar setname Oc Ns …
  53 .Ar filesystem Ns | Ns Ar volume
  54 .Nm zfs
  55 .Cm allow
  56 .Fl c
  57 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  58 .Ar setname Oc Ns …
  59 .Ar filesystem Ns | Ns Ar volume
  60 .Nm zfs
  61 .Cm allow
  62 .Fl s No @ Ns Ar setname
  63 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  64 .Ar setname Oc Ns …
  65 .Ar filesystem Ns | Ns Ar volume
  66 .Nm zfs
  67 .Cm unallow
  68 .Op Fl dglru
  69 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns …
  70 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  71 .Ar setname Oc Ns … Oc
  72 .Ar filesystem Ns | Ns Ar volume
  73 .Nm zfs
  74 .Cm unallow
  75 .Op Fl dlr
  76 .Fl e Ns | Ns Sy everyone
  77 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  78 .Ar setname Oc Ns … Oc
  79 .Ar filesystem Ns | Ns Ar volume
  80 .Nm zfs
  81 .Cm unallow
  82 .Op Fl r
  83 .Fl c
  84 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  85 .Ar setname Oc Ns … Oc
  86 .Ar filesystem Ns | Ns Ar volume
  87 .Nm zfs
  88 .Cm unallow
  89 .Op Fl r
  90 .Fl s No @ Ns Ar setname
  91 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
  92 .Ar setname Oc Ns … Oc
  93 .Ar filesystem Ns | Ns Ar volume
  94 .
  95 .Sh DESCRIPTION
  96 .Bl -tag -width ""
  97 .It Xo
  98 .Nm zfs
  99 .Cm allow
 100 .Ar filesystem Ns | Ns Ar volume
 101 .Xc
 102 Displays permissions that have been delegated on the specified filesystem or
 103 volume.
 104 See the other forms of
 105 .Nm zfs Cm allow
 106 for more information.
 107 .Pp
 108 Delegations are supported under Linux with the exception of
 109 .Sy mount ,
 110 .Sy unmount ,
 111 .Sy mountpoint ,
 112 .Sy canmount ,
 113 .Sy rename ,
 114 and
 115 .Sy share .
 116 These permissions cannot be delegated because the Linux
 117 .Xr mount 8
 118 command restricts modifications of the global namespace to the root user.
 119 .It Xo
 120 .Nm zfs
 121 .Cm allow
 122 .Op Fl dglu
 123 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns …
 124 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 125 .Ar setname Oc Ns …
 126 .Ar filesystem Ns | Ns Ar volume
 127 .Xc
 128 .It Xo
 129 .Nm zfs
 130 .Cm allow
 131 .Op Fl dl
 132 .Fl e Ns | Ns Sy everyone
 133 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 134 .Ar setname Oc Ns …
 135 .Ar filesystem Ns | Ns Ar volume
 136 .Xc
 137 Delegates ZFS administration permission for the file systems to non-privileged
 138 users.
 139 .Bl -tag -width "-d"
 140 .It Fl d
 141 Allow only for the descendent file systems.
 142 .It Fl e Ns | Ns Sy everyone
 143 Specifies that the permissions be delegated to everyone.
 144 .It Fl g Ar group Ns Oo , Ns Ar group Oc Ns …
 145 Explicitly specify that permissions are delegated to the group.
 146 .It Fl l
 147 Allow
 148 .Qq locally
 149 only for the specified file system.
 150 .It Fl u Ar user Ns Oo , Ns Ar user Oc Ns …
 151 Explicitly specify that permissions are delegated to the user.
 152 .It Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns …
 153 Specifies to whom the permissions are delegated.
 154 Multiple entities can be specified as a comma-separated list.
 155 If neither of the
 156 .Fl gu
 157 options are specified, then the argument is interpreted preferentially as the
 158 keyword
 159 .Sy everyone ,
 160 then as a user name, and lastly as a group name.
 161 To specify a user or group named
 162 .Qq everyone ,
 163 use the
 164 .Fl g
 165 or
 166 .Fl u
 167 options.
 168 To specify a group with the same name as a user, use the
 169 .Fl g
 170 options.
 171 .It Xo
 172 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 173 .Ar setname Oc Ns …
 174 .Xc
 175 The permissions to delegate.
 176 Multiple permissions may be specified as a comma-separated list.
 177 Permission names are the same as ZFS subcommand and property names.
 178 See the property list below.
 179 Property set names, which begin with
 180 .Sy @ ,
 181 may be specified.
 182 See the
 183 .Fl s
 184 form below for details.
 185 .El
 186 .Pp
 187 If neither of the
 188 .Fl dl
 189 options are specified, or both are, then the permissions are allowed for the
 190 file system or volume, and all of its descendents.
 191 .Pp
 192 Permissions are generally the ability to use a ZFS subcommand or change a ZFS
 193 property.
 194 The following permissions are available:
 195 .TS
 196 l l l .
 197 NAME    TYPE    NOTES
 198 _       _       _
 199 allow   subcommand      Must also have the permission that is being allowed
 200 bookmark        subcommand
 201 clone   subcommand      Must also have the \fBcreate\fR ability and \fBmount\fR ability in the origin file system
 202 create  subcommand      Must also have the \fBmount\fR ability. Must also have the \fBrefreservation\fR ability to create a non-sparse volume.
 203 destroy subcommand      Must also have the \fBmount\fR ability
 204 diff    subcommand      Allows lookup of paths within a dataset given an object number, and the ability to create snapshots necessary to \fBzfs diff\fR.
 205 hold    subcommand      Allows adding a user hold to a snapshot
 206 load-key        subcommand      Allows loading and unloading of encryption key (see \fBzfs load-key\fR and \fBzfs unload-key\fR).
 207 change-key      subcommand      Allows changing an encryption key via \fBzfs change-key\fR.
 208 mount   subcommand      Allows mounting/umounting ZFS datasets
 209 promote subcommand      Must also have the \fBmount\fR and \fBpromote\fR ability in the origin file system
 210 receive subcommand      Must also have the \fBmount\fR and \fBcreate\fR ability
 211 release subcommand      Allows releasing a user hold which might destroy the snapshot
 212 rename  subcommand      Must also have the \fBmount\fR and \fBcreate\fR ability in the new parent
 213 rollback        subcommand      Must also have the \fBmount\fR ability
 214 send    subcommand
 215 share   subcommand      Allows sharing file systems over NFS or SMB protocols
 216 snapshot        subcommand      Must also have the \fBmount\fR ability
 217
 218 groupquota      other   Allows accessing any \fBgroupquota@\fI…\fR property
 219 groupobjquota   other   Allows accessing any \fBgroupobjquota@\fI…\fR property
 220 groupused       other   Allows reading any \fBgroupused@\fI…\fR property
 221 groupobjused    other   Allows reading any \fBgroupobjused@\fI…\fR property
 222 userprop        other   Allows changing any user property
 223 userquota       other   Allows accessing any \fBuserquota@\fI…\fR property
 224 userobjquota    other   Allows accessing any \fBuserobjquota@\fI…\fR property
 225 userused        other   Allows reading any \fBuserused@\fI…\fR property
 226 userobjused     other   Allows reading any \fBuserobjused@\fI…\fR property
 227 projectobjquota other   Allows accessing any \fBprojectobjquota@\fI…\fR property
 228 projectquota    other   Allows accessing any \fBprojectquota@\fI…\fR property
 229 projectobjused  other   Allows reading any \fBprojectobjused@\fI…\fR property
 230 projectused     other   Allows reading any \fBprojectused@\fI…\fR property
 231
 232 aclinherit      property
 233 aclmode property
 234 acltype property
 235 atime   property
 236 canmount        property
 237 casesensitivity property
 238 checksum        property
 239 compression     property
 240 context property
 241 copies  property
 242 dedup   property
 243 defcontext      property
 244 devices property
 245 dnodesize       property
 246 encryption      property
 247 exec    property
 248 filesystem_limit        property
 249 fscontext       property
 250 keyformat       property
 251 keylocation     property
 252 logbias property
 253 mlslabel        property
 254 mountpoint      property
 255 nbmand  property
 256 normalization   property
 257 overlay property
 258 pbkdf2iters     property
 259 primarycache    property
 260 quota   property
 261 readonly        property
 262 recordsize      property
 263 redundant_metadata      property
 264 refquota        property
 265 refreservation  property
 266 relatime        property
 267 reservation     property
 268 rootcontext     property
 269 secondarycache  property
 270 setuid  property
 271 sharenfs        property
 272 sharesmb        property
 273 snapdev property
 274 snapdir property
 275 snapshot_limit  property
 276 special_small_blocks    property
 277 sync    property
 278 utf8only        property
 279 version property
 280 volblocksize    property
 281 volmode property
 282 volsize property
 283 vscan   property
 284 xattr   property
 285 zoned   property
 286 .TE
 287 .It Xo
 288 .Nm zfs
 289 .Cm allow
 290 .Fl c
 291 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 292 .Ar setname Oc Ns …
 293 .Ar filesystem Ns | Ns Ar volume
 294 .Xc
 295 Sets
 296 .Qq create time
 297 permissions.
 298 These permissions are granted
 299 .Pq locally
 300 to the creator of any newly-created descendent file system.
 301 .It Xo
 302 .Nm zfs
 303 .Cm allow
 304 .Fl s No @ Ns Ar setname
 305 .Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 306 .Ar setname Oc Ns …
 307 .Ar filesystem Ns | Ns Ar volume
 308 .Xc
 309 Defines or adds permissions to a permission set.
 310 The set can be used by other
 311 .Nm zfs Cm allow
 312 commands for the specified file system and its descendents.
 313 Sets are evaluated dynamically, so changes to a set are immediately reflected.
 314 Permission sets follow the same naming restrictions as ZFS file systems, but the
 315 name must begin with
 316 .Sy @ ,
 317 and can be no more than 64 characters long.
 318 .It Xo
 319 .Nm zfs
 320 .Cm unallow
 321 .Op Fl dglru
 322 .Ar user Ns | Ns Ar group Ns Oo , Ns Ar user Ns | Ns Ar group Oc Ns …
 323 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 324 .Ar setname Oc Ns … Oc
 325 .Ar filesystem Ns | Ns Ar volume
 326 .Xc
 327 .It Xo
 328 .Nm zfs
 329 .Cm unallow
 330 .Op Fl dlr
 331 .Fl e Ns | Ns Sy everyone
 332 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 333 .Ar setname Oc Ns … Oc
 334 .Ar filesystem Ns | Ns Ar volume
 335 .Xc
 336 .It Xo
 337 .Nm zfs
 338 .Cm unallow
 339 .Op Fl r
 340 .Fl c
 341 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 342 .Ar setname Oc Ns … Oc
 343 .Ar filesystem Ns | Ns Ar volume
 344 .Xc
 345 Removes permissions that were granted with the
 346 .Nm zfs Cm allow
 347 command.
 348 No permissions are explicitly denied, so other permissions granted are still in
 349 effect.
 350 For example, if the permission is granted by an ancestor.
 351 If no permissions are specified, then all permissions for the specified
 352 .Ar user ,
 353 .Ar group ,
 354 or
 355 .Sy everyone
 356 are removed.
 357 Specifying
 358 .Sy everyone
 359 .Po or using the
 360 .Fl e
 361 option
 362 .Pc
 363 only removes the permissions that were granted to everyone, not all permissions
 364 for every user and group.
 365 See the
 366 .Nm zfs Cm allow
 367 command for a description of the
 368 .Fl ldugec
 369 options.
 370 .Bl -tag -width "-r"
 371 .It Fl r
 372 Recursively remove the permissions from this file system and all descendents.
 373 .El
 374 .It Xo
 375 .Nm zfs
 376 .Cm unallow
 377 .Op Fl r
 378 .Fl s No @ Ns Ar setname
 379 .Oo Ar perm Ns | Ns @ Ns Ar setname Ns Oo , Ns Ar perm Ns | Ns @ Ns
 380 .Ar setname Oc Ns … Oc
 381 .Ar filesystem Ns | Ns Ar volume
 382 .Xc
 383 Removes permissions from a permission set.
 384 If no permissions are specified, then all permissions are removed, thus removing
 385 the set entirely.
 386 .El
 387 .
 388 .Sh EXAMPLES
 389 .\" These are, respectively, examples 17, 18, 19, 20 from zfs.8
 390 .\" Make sure to update them bidirectionally
 391 .Ss Example 1 : No Delegating ZFS Administration Permissions on a ZFS Dataset
 392 The following example shows how to set permissions so that user
 393 .Ar cindys
 394 can create, destroy, mount, and take snapshots on
 395 .Ar tank/cindys .
 396 The permissions on
 397 .Ar tank/cindys
 398 are also displayed.
 399 .Bd -literal -compact -offset Ds
 400 .No # Nm zfs Cm allow Sy cindys create , Ns Sy destroy , Ns Sy mount , Ns Sy snapshot Ar tank/cindys
 401 .No # Nm zfs Cm allow Ar tank/cindys
 402 ---- Permissions on tank/cindys --------------------------------------
 403 Local+Descendent permissions:
 404         user cindys create,destroy,mount,snapshot
 405 .Ed
 406 .Pp
 407 Because the
 408 .Ar tank/cindys
 409 mount point permission is set to 755 by default, user
 410 .Ar cindys
 411 will be unable to mount file systems under
 412 .Ar tank/cindys .
 413 Add an ACE similar to the following syntax to provide mount point access:
 414 .Dl # Cm chmod No A+user : Ns Ar cindys Ns :add_subdirectory:allow Ar /tank/cindys
 415 .
 416 .Ss Example 2 : No Delegating Create Time Permissions on a ZFS Dataset
 417 The following example shows how to grant anyone in the group
 418 .Ar staff
 419 to create file systems in
 420 .Ar tank/users .
 421 This syntax also allows staff members to destroy their own file systems, but not
 422 destroy anyone else's file system.
 423 The permissions on
 424 .Ar tank/users
 425 are also displayed.
 426 .Bd -literal -compact -offset Ds
 427 .No # Nm zfs Cm allow Ar staff Sy create , Ns Sy mount Ar tank/users
 428 .No # Nm zfs Cm allow Fl c Sy destroy Ar tank/users
 429 .No # Nm zfs Cm allow Ar tank/users
 430 ---- Permissions on tank/users ---------------------------------------
 431 Permission sets:
 432         destroy
 433 Local+Descendent permissions:
 434         group staff create,mount
 435 .Ed
 436 .
 437 .Ss Example 3 : No Defining and Granting a Permission Set on a ZFS Dataset
 438 The following example shows how to define and grant a permission set on the
 439 .Ar tank/users
 440 file system.
 441 The permissions on
 442 .Ar tank/users
 443 are also displayed.
 444 .Bd -literal -compact -offset Ds
 445 .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
 446 .No # Nm zfs Cm allow staff No @ Ns Ar pset tank/users
 447 .No # Nm zfs Cm allow Ar tank/users
 448 ---- Permissions on tank/users ---------------------------------------
 449 Permission sets:
 450         @pset create,destroy,mount,snapshot
 451 Local+Descendent permissions:
 452         group staff @pset
 453 .Ed
 454 .
 455 .Ss Example 4 : No Delegating Property Permissions on a ZFS Dataset
 456 The following example shows to grant the ability to set quotas and reservations
 457 on the
 458 .Ar users/home
 459 file system.
 460 The permissions on
 461 .Ar users/home
 462 are also displayed.
 463 .Bd -literal -compact -offset Ds
 464 .No # Nm zfs Cm allow Ar cindys Sy quota , Ns Sy reservation Ar users/home
 465 .No # Nm zfs Cm allow Ar users/home
 466 ---- Permissions on users/home ---------------------------------------
 467 Local+Descendent permissions:
 468         user cindys quota,reservation
 469 cindys% zfs set quota=10G users/home/marks
 470 cindys% zfs get quota users/home/marks
 471 NAME              PROPERTY  VALUE  SOURCE
 472 users/home/marks  quota     10G    local
 473 .Ed
 474 .
 475 .Ss Example 5 : No Removing ZFS Delegated Permissions on a ZFS Dataset
 476 The following example shows how to remove the snapshot permission from the
 477 .Ar staff
 478 group on the
 479 .Sy tank/users
 480 file system.
 481 The permissions on
 482 .Sy tank/users
 483 are also displayed.
 484 .Bd -literal -compact -offset Ds
 485 .No # Nm zfs Cm unallow Ar staff Sy snapshot Ar tank/users
 486 .No # Nm zfs Cm allow Ar tank/users
 487 ---- Permissions on tank/users ---------------------------------------
 488 Permission sets:
 489         @pset create,destroy,mount,snapshot
 490 Local+Descendent permissions:
 491         group staff @pset
 492 .Ed