1 SHAREMGR(1M) Maintenance Commands SHAREMGR(1M) 2 3 4 5 NAME 6 sharemgr - configure and manage file sharing 7 8 SYNOPSIS 9 sharemgr subcommand [options] 10 11 12 add-share [-nth] [-r resource-name] [-d "description text"] 13 -s sharepath group 14 15 16 create [-nvh] [-P proto [-p property=value]] group 17 18 19 delete [-nvh] [-P proto] [-f] group 20 21 22 disable [-nvh] [-a | group...] 23 24 25 enable [-nvh] [-a | group...] 26 27 28 list [-vh] [-P proto] 29 30 31 move-share [-nv] -s sharepath destination-group 32 33 34 remove-share [-fnvh] -s sharepath group 35 36 37 set [-nvh] -P proto [-p property=value]... [-S optionset] 38 [-s sharepath] group 39 40 41 set-share [-nh] [-r resource] [-d "description text"] 42 -s sharepath group 43 44 45 show [-pvxh] [-P proto] [group]... 46 47 48 unset [-nvh] -P proto [-S optionset] [-p property]... 49 group 50 51 52 share [-F fstype] [-p] [-o optionlist] [-d description] 53 [pathname [resourcename]] 54 55 56 unshare [-F fstype] [-p] [-o optionlist] sharepath 57 58 59 DESCRIPTION 60 The sharemgr command configures share groups and the shares contained 61 within them. 62 63 64 A group name must conform to service management facility (SMF) (see 65 smf(5)) service-naming conventions, thus is limited to starting with an 66 alphabetic character, with the rest of the name consisting only of 67 alphanumeric characters plus - (hyphen) and _ (underbar). 68 69 70 Subcommands that result in a configuration change support a dry-run 71 option. When dry-run (-n) is specified, the syntax and validity of the 72 command is tested but the configuration is not actually updated. 73 74 75 For all subcommands, the -h option lists usage and help information. 76 77 78 For subcommands with the verbose (-v) option, additional information 79 will be provided. For example, in conjunction with the -n option, 80 verbose mode will also indicate whether the current user has sufficient 81 permissions to accomplish the operation. 82 83 84 There are two groups that are created automatically. The default group 85 always exists and covers legacy NFS shares only. The zfs group will be 86 created when ZFS shares are enabled. 87 88 89 The options shown in the SYNOPSIS section are described in the context 90 of each subcommand. All subcommands except list and show require root 91 privileges or that you assume the Primary Administrator role. 92 93 Subcommands 94 With no subcommand entered, a sharemgr command with the -h option 95 displays a usage message for all subcommands. 96 97 98 The following subcommands follow sharemgr on a command line. Commands 99 take the form: 100 101 % sharemgr <subcommand> [options] 102 103 104 105 create [-nvh] [-P proto [-p property=value]] group 106 107 Create a new group with specified name. 108 109 If -n is specified, the command checks only the validity of the 110 command and that the group does not already exist. 111 112 If no protocol is specified, all known protocols are enabled for 113 the specified group. If a protocol is specified, only that protocol 114 is enabled. You can specify properties for a specified protocol. 115 116 If group exists, use of -P adds the specified protocol to that 117 group. 118 119 As an example of the create subcommand, the following command 120 creates a new group with the name mygroup. 121 122 # sharemgr create mygroup 123 124 125 Because no protocol was specified in the preceding command, all 126 defined protocols will be enabled on the group. 127 128 129 delete [-nvh] [-P proto] [-f] group 130 131 Delete the specified group. If the group is not empty, you can use 132 the -f option to force the deletion, which unshares and removes all 133 shares from the group before removing the group itself. 134 135 If you specify a protocol, rather than deleting the whole group, 136 this subcommand deletes the protocol from the group. 137 138 The -n option can be used to test the syntax of the command. 139 140 As an example, the following command removes the group mygroup from 141 the configuration if it is empty. 142 143 # sharemgr delete mygroup 144 145 146 The following command removes any existing shares prior to removing 147 the group. 148 149 # sharemgr delete -f mygroup 150 151 152 Note the use of the force (-f) option, above. 153 154 155 list [-vh] [-P proto] 156 157 List the defined groups. 158 159 If a protocol is specified, list only those groups that have the 160 specified protocol defined. 161 162 If the verbose option is specified, the current state of the group 163 and all protocols enabled on the group are listed as well. For 164 example: 165 166 # sharemgr list -v 167 mygroup enabled nfs 168 rdonlygrp disabled nfs 169 170 171 172 173 show [-pvxh] [-P proto] [group...] 174 175 Shows the contents of the specified group(s). 176 177 If the verbose option is specified, the resource name and 178 description of each share is displayed if they are defined. 179 Otherwise, only the share paths are displayed. Also, when temporary 180 shares are listed, they are prefixed with an asterisk (*). 181 182 If the -p option is specified, all options defined for the 183 protocols of the group are displayed, in addition to the display 184 without options. If the -P option is used, the output is limited to 185 those groups that have the specified protocol enabled. If the -x 186 option is specified, output is in XML format and the -p and -v 187 options are ignored, because all information is included in the 188 XML. 189 190 The following example illustrates the use of the -p option. 191 192 # sharemgr show -p mygroup 193 default nfs=() 194 * /data/backup 195 mygroup nfs=(nosuid=true) 196 /export/home/home0 197 /export/home/home1 198 199 200 The following example illustrates the use of the -v option. 201 202 # sharemgr show -v mygroup 203 mygroup 204 HOME0=/export/home/home0 "Home directory set 0" 205 HOME1=/export/home/home1 "Home directory set 1" 206 207 208 ZFS managed shares are handled in a way similar to the way NFS 209 shares are handled. These shares appear as subgroups within the 210 parent group zfs. The subgroups are always prefixed with zfs/ and 211 use the ZFS dataset name for the rest of the name. The mount point 212 and any sub-mounts that inherit sharing are shown as the shares of 213 the subgroup. For example: 214 215 # sharemgr show -vp zfs 216 zfs nfs=() 217 zfs/ztest 218 /ztest 219 /ztest/backups 220 221 222 223 224 set [-nvh] -P proto [-S optionset] [-p property=value]* [-s share path] 225 group 226 227 Set protocol-specific properties on the specified group. 228 229 The -P option is required and must specify a valid protocol. 230 231 Optionsets are protocol-specific sets of properties that can be 232 negotiated by the protocol client. For NFS, optionsets are 233 equivalent to security modes as defined in nfssec(5). If -S 234 optionset is specified, the properties are applied to the selected 235 optionset. Otherwise they are applied to the general optionset. 236 237 Together, -P and -S select a specific view of the group's options 238 on which to work. 239 240 Property values are strings. A specified property is set to a new 241 value if the property already exists or is added to the protocol if 242 it does not already exist. 243 244 In the general case, at least one property must be set. If -S is 245 specified, properties can be omitted and the specified optionset is 246 enabled for the protocol. 247 248 The -s option allows setting properties on a per-share basis. While 249 this is supported, it should be limited to managing legacy shares 250 and to the occasional need for an override of a group-level 251 property or placing an additional property on one share within a 252 group. 253 254 An example of this subcommand: 255 256 # sharemgr set -P nfs -p anon=1234 mygroup 257 258 259 The preceding command adds the property anon=1234 to the nfs view 260 of group mygroup. If mygroup has existing shares, they will all be 261 reshared with the new property value(s). 262 263 264 unset [-nvh] -P proto [-S optionset] [-p property]* [-s sharepath ] 265 group 266 267 Unset the specified properties for the protocol or for the 268 specified optionset of the protocol. 269 270 In the general case, at least one property must be set. If -S is 271 specified, properties can be omitted and the specified optionset is 272 removed from the protocol. 273 274 The -s option allows removing a share-specific property. 275 276 An example of this subcommand: 277 278 # sharemgr unset -P nfs -p anon mygroup 279 280 281 The preceding command removes the anon= property from the nfs view 282 of group mygroup. If mygroup has existing shares, they will all be 283 reshared with the new property value(s). 284 285 286 add-share [-nth] [-r resource-name] [-d "description text"] -s 287 sharepath group 288 289 Add a new share to the specified group. 290 291 The -s option is mandatory and takes a full directory path. 292 293 If either or both of -d and -r are specified, they specify values 294 associated with the share. -d provides a description string to 295 document the share and -r provides a protocol-independent resource 296 name. Resource names are not used by NFS at this time but can be 297 specified. These names currently follow the same naming rules as 298 group names. 299 300 The temporary option (-t) results in the share being shared but not 301 stored in the configuration repository. This option is intended for 302 shares that should not survive a reboot or server restart, or for 303 testing purposes. Temporary shares are indicated in the show 304 subcommand output with an asterisk (*) preceding the share. 305 306 If sharepath is a ZFS path and that path is added to the zfs group, 307 sharemgr creates a new ZFS subgroup; the new share is added to that 308 subgroup. Any ZFS sub-filesystems under the ZFS filesystem 309 designated by sharepath will inherit the shared status of 310 sharepath. 311 312 The effect of the add-share subcommand on a ZFS dataset is 313 determined by the values of the sharesmb and sharenfs properties of 314 that dataset. 315 316 See zfs(1M) for a description of the sharesmb and sharenfs 317 properties. 318 319 The following are examples of the add-share subcommand. 320 321 # sharemgr add-share -s /export/home/home0 -d "home \ 322 directory set 0" -r HOME0 mygroup 323 324 # sharemgr add-share -s /export/home/home1 -d "home \ 325 directory set 1" -r HOME1 mygroup 326 327 328 The preceding commands add /export/home/home0 and 329 /export/home/home1 to the group mygroup. A descriptive comment and 330 a resource name are included. 331 332 333 move-share [-nvh] -s sharepath destination-group 334 335 Move the specified share from the group it is currently in to the 336 specified destination group. The move-share subcommand does not 337 create a group. A specified group must exist for the command to 338 succeed. 339 340 The following is an example of this subcommand. 341 342 # sharemgr move-share -s /export/home/home1 newgroup 343 344 345 Assuming /export/home/home1 is in the group mygroup, the preceding 346 command moves /export/home/home1 to the group newgroup and unshares 347 and then reshares the directory with the properties associated with 348 newgroup. 349 350 351 remove-share [-fnvh] -s sharepath group 352 353 Remove the specified share from the specified group. The force (-f) 354 option forces the share to be removed even if it is busy. 355 356 You must specify the full path for sharepath. For group, use the 357 subgroup as displayed in the output of the sharemgr show command. 358 Note that if there are subshares that were created by inheritance, 359 these will be removed, along with the parent shares. 360 361 362 set-share [-nvh] [-r resource] [-d "description text"] -s sharepath 363 group 364 365 Set or change the specified share's description and resource 366 values. One use of set-share is to rename a resource. The syntax 367 for this use of the subcommand is: 368 369 # sharemgr set-share -r current_name=new_name -s sharepath group 370 371 372 373 374 enable [-nvh] [group... | -a] 375 376 Enable the specified group(s), or (with -a) all groups, and start 377 sharing the contained shares. This state persists across reboots. 378 379 An enabled group will be shared whenever the corresponding SMF 380 service instance is enabled. sharemgr will start the SMF service 381 instance if it is not currently online. 382 383 384 disable [-nvh] [group... | -a] 385 386 Disable the specified group(s), or (with -a) all groups, and 387 unshare the shares that they contain. This state persists across 388 reboots. 389 390 A disabled group will not be shared even if the corresponding SMF 391 service instance is online. This feature is useful when you do not 392 want a group of shares to be started at boot time. 393 394 395 start [-vh] [-P proto] [group... | -a] 396 397 Start the specified group, or (with -a) all groups. The start 398 subcommand is similar to enable in that all shares are started, but 399 start works only on groups that are enabled. start is used by the 400 SMF to start sharing at system boot. 401 402 A group will not start sharing if it is in the sharemgr disabled 403 state. However, the corresponding SMF service instance will be 404 started. 405 406 Note that the start subcommand is similar to the shareall(1M) 407 command in that it starts up only the configured shares. That is, 408 the enabled shares will start being shared, but the configuration 409 state is left the same. The command: 410 411 # sharemgr start -a 412 413 414 ...is equivalent to: 415 416 # shareall 417 418 419 420 421 stop [-vh] [-P proto] [group... | -a] 422 423 Stop the specified group, or (with -a) all groups. The stop 424 subcommand is similar to disable in that all shares are no longer 425 shared, but it works only on groups that are enabled. stop is used 426 by the SMF to stop sharing at system shutdown. 427 428 Note that the stop subcommand is similar to the unshareall(1M) 429 command in that all active shares are unshared, but the 430 configuration is left the same. That is, the shares are stopped but 431 the service instances are left enabled. The command: 432 433 # sharemgr stop -a 434 435 436 ...is equivalent to: 437 438 # unshareall 439 440 441 442 443 share [-F fstype] [-p] [-o optionlist] [-d description] [pathname 444 [resourcename]] 445 446 Shares the specified path in the default share group. This 447 subcommand implements the share(1M) functionality. Shares that are 448 shared in this manner will be transient shares. Use of the -p 449 option causes the shares to be persistent. 450 451 452 unshare [-F fstype] [-p] [-o optionlist] sharepath 453 454 Unshares the specified share. This subcommand implements the 455 unshare(1M) functionality. By default, the unshare is temporary. 456 The -p option is provided to remove the share from the 457 configuration in a way that persists across reboots. 458 459 460 EXIT STATUS 461 0 462 Successful completion. 463 464 465 98 466 Service is offline and cannot be enabled (start 467 only). 468 469 470 other non-zero 471 Command failed. 472 473 474 FILES 475 /usr/include/libshare.h 476 Error codes used for exit status. 477 478 479 ATTRIBUTES 480 See attributes(5) for descriptions of the following attributes: 481 482 483 484 485 +--------------------+-----------------+ 486 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 487 +--------------------+-----------------+ 488 |Interface Stability | Committed | 489 +--------------------+-----------------+ 490 491 SEE ALSO 492 idmap(1M), sharectl(1M), zfs(1M), attributes(5), nfssec(5), 493 shareacl(5), sharenfs(5), sharesmb(5), smf(5), standards(5) 494 495 496 497 September 5, 2017 SHAREMGR(1M)