1 '\" te 2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved 3 .\" Copyright 2017 Nexenta Systems, Inc. All rights reserved. 4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. 5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with 6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 7 .TH SHAREMGR 1M "Sep 5, 2017" 8 .SH NAME 9 sharemgr \- configure and manage file sharing 10 .SH SYNOPSIS 11 .LP 12 .nf 13 \fBsharemgr\fR \fIsubcommand\fR [\fIoptions\fR] 14 .fi 15 16 .LP 17 .nf 18 \fBadd-share\fR [\fB-nth\fR] [\fB-r\fR \fIresource-name\fR] [\fB-d\fR "\fIdescription text\fR"] 19 \fB-s\fR \fIsharepath\fR \fIgroup\fR 20 .fi 21 22 .LP 23 .nf 24 \fBcreate\fR [\fB-nvh\fR] [\fB-P\fR \fIproto\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]] \fIgroup\fR 25 .fi 26 27 .LP 28 .nf 29 \fBdelete\fR [\fB-nvh\fR] [\fB-P\fR \fIproto\fR] [\fB-f\fR] \fIgroup\fR 30 .fi 31 32 .LP 33 .nf 34 \fBdisable\fR [\fB-nvh\fR] [\fB-a\fR | \fIgroup\fR...] 35 .fi 36 37 .LP 38 .nf 39 \fBenable\fR [\fB-nvh\fR] [\fB-a\fR | \fIgroup\fR...] 40 .fi 41 42 .LP 43 .nf 44 \fBlist\fR [\fB-vh\fR] [\fB-P\fR \fIproto\fR] 45 .fi 46 47 .LP 48 .nf 49 \fBmove-share\fR [\fB-nv\fR] \fB-s\fR \fIsharepath\fR \fIdestination-group\fR 50 .fi 51 52 .LP 53 .nf 54 \fBremove-share\fR [\fB-fnvh\fR] \fB-s\fR \fIsharepath\fR \fIgroup\fR 55 .fi 56 57 .LP 58 .nf 59 \fBset\fR [\fB-nvh\fR] \fB-P\fR \fIproto\fR [\fB-p\fR \fIproperty\fR=\fIvalue\fR]... [\fB-S\fR \fIoptionset\fR] 60 [\fB-s\fR \fIsharepath\fR] \fIgroup\fR 61 .fi 62 63 .LP 64 .nf 65 \fBset-share\fR [\fB-nh\fR] [\fB-r\fR \fIresource\fR] [\fB-d\fR "\fIdescription text\fR"] 66 \fB-s\fR \fIsharepath\fR \fIgroup\fR 67 .fi 68 69 .LP 70 .nf 71 \fBshow\fR [\fB-pvxh\fR] [\fB-P\fR \fIproto\fR] [\fIgroup\fR]... 72 .fi 73 74 .LP 75 .nf 76 \fBunset\fR [\fB-nvh\fR] \fB-P\fR \fIproto\fR [\fB-S\fR \fIoptionset\fR] [\fB-p\fR \fIproperty\fR]... 77 \fIgroup\fR 78 .fi 79 80 .LP 81 .nf 82 \fBshare\fR [\fB-F\fR \fIfstype\fR] [\fB-p\fR] [\fB-o\fR \fIoptionlist\fR] [\fB-d\fR \fIdescription\fR] 83 [\fIpathname\fR [\fIresourcename\fR]] 84 .fi 85 86 .LP 87 .nf 88 \fBunshare\fR [\fB-F\fR \fIfstype\fR] [\fB-p\fR] [\fB-o\fR \fIoptionlist\fR] \fIsharepath\fR 89 .fi 90 91 .SH DESCRIPTION 92 .LP 93 The \fBsharemgr\fR command configures share groups and the shares contained 94 within them. 95 .sp 96 .LP 97 A group name must conform to service management facility (SMF) (see 98 \fBsmf\fR(5)) service-naming conventions, thus is limited to starting with an 99 alphabetic character, with the rest of the name consisting only of alphanumeric 100 characters plus \fB-\fR (hyphen) and \fB_\fR (underbar). 101 .sp 102 .LP 103 Subcommands that result in a configuration change support a dry-run option. 104 When dry-run (\fB-n\fR) is specified, the syntax and validity of the command is 105 tested but the configuration is not actually updated. 106 .sp 107 .LP 108 For all subcommands, the \fB-h\fR option lists usage and help information. 109 .sp 110 .LP 111 For subcommands with the verbose (\fB-v\fR) option, additional information will 112 be provided. For example, in conjunction with the \fB-n\fR option, verbose mode 113 will also indicate whether the current user has sufficient permissions to 114 accomplish the operation. 115 .sp 116 .LP 117 There are two groups that are created automatically. The \fBdefault\fR group 118 always exists and covers legacy NFS shares only. The \fBzfs\fR group will be 119 created when ZFS shares are enabled. 120 .sp 121 .LP 122 The options shown in the SYNOPSIS section are described in the context of each 123 subcommand. All subcommands except \fBlist\fR and \fBshow\fR require root 124 privileges or that you assume the Primary Administrator role. 125 .SS "Subcommands" 126 .LP 127 With no subcommand entered, a \fBsharemgr\fR command with the \fB-h\fR option 128 displays a usage message for all subcommands. 129 .sp 130 .LP 131 The following subcommands follow \fBsharemgr\fR on a command line. Commands 132 take the form: 133 .sp 134 .in +2 135 .nf 136 % \fBsharemgr \fI<subcommand>\fR [\fIoptions\fR]\fR 137 .fi 138 .in -2 139 .sp 140 141 .sp 142 .ne 2 143 .na 144 \fB\fBcreate\fR \fB[-nvh] [-P \fIproto\fR [-p \fIproperty\fR=\fIvalue\fR]] 145 \fIgroup\fR\fR\fR 146 .ad 147 .sp .6 148 .RS 4n 149 Create a new group with specified name. 150 .sp 151 If \fB-n\fR is specified, the command checks only the validity of the command 152 and that the group does not already exist. 153 .sp 154 If no protocol is specified, all known protocols are enabled for the specified 155 group. If a protocol is specified, only that protocol is enabled. You can 156 specify properties for a specified protocol. 157 .sp 158 If \fIgroup\fR exists, use of \fB-P\fR adds the specified protocol to that 159 group. 160 .sp 161 As an example of the \fBcreate\fR subcommand, the following command creates a 162 new group with the name \fBmygroup\fR. 163 .sp 164 .in +2 165 .nf 166 # \fBsharemgr create mygroup\fR 167 .fi 168 .in -2 169 .sp 170 171 Because no protocol was specified in the preceding command, all defined 172 protocols will be enabled on the group. 173 .RE 174 175 .sp 176 .ne 2 177 .na 178 \fB\fBdelete\fR \fB[-nvh] [-P \fIproto\fR] [-f] \fIgroup\fR\fR\fR 179 .ad 180 .sp .6 181 .RS 4n 182 Delete the specified group. If the group is not empty, you can use the \fB-f\fR 183 option to force the deletion, which unshares and removes all shares from the 184 group before removing the group itself. 185 .sp 186 If you specify a protocol, rather than deleting the whole group, this 187 subcommand deletes the protocol from the group. 188 .sp 189 The \fB-n\fR option can be used to test the syntax of the command. 190 .sp 191 As an example, the following command removes the group \fBmygroup\fR from the 192 configuration if it is empty. 193 .sp 194 .in +2 195 .nf 196 # \fBsharemgr delete mygroup\fR 197 .fi 198 .in -2 199 .sp 200 201 The following command removes any existing shares prior to removing the group. 202 .sp 203 .in +2 204 .nf 205 # \fBsharemgr delete -f mygroup\fR 206 .fi 207 .in -2 208 .sp 209 210 Note the use of the force (\fB-f\fR) option, above. 211 .RE 212 213 .sp 214 .ne 2 215 .na 216 \fB\fBlist\fR \fB[-vh] [-P \fIproto\fR]\fR\fR 217 .ad 218 .sp .6 219 .RS 4n 220 List the defined groups. 221 .sp 222 If a protocol is specified, list only those groups that have the specified 223 protocol defined. 224 .sp 225 If the verbose option is specified, the current state of the group and all 226 protocols enabled on the group are listed as well. For example: 227 .sp 228 .in +2 229 .nf 230 # \fBsharemgr list -v\fR 231 mygroup enabled nfs 232 rdonlygrp disabled nfs 233 .fi 234 .in -2 235 .sp 236 237 .RE 238 239 .sp 240 .ne 2 241 .na 242 \fB\fBshow\fR \fB[-pvxh] [-P \fIproto\fR] [\fIgroup\fR...]\fR\fR 243 .ad 244 .sp .6 245 .RS 4n 246 Shows the contents of the specified group(s). 247 .sp 248 If the verbose option is specified, the resource name and description of each 249 share is displayed if they are defined. Otherwise, only the share paths are 250 displayed. Also, when temporary shares are listed, they are prefixed with an 251 asterisk (\fB*\fR). 252 .sp 253 If the \fB-p\fR option is specified, all options defined for the protocols of 254 the group are displayed, in addition to the display without options. If the 255 \fB-P\fR option is used, the output is limited to those groups that have the 256 specified protocol enabled. If the \fB-x\fR option is specified, output is in 257 XML format and the \fB-p\fR and \fB-v\fR options are ignored, because all 258 information is included in the XML. 259 .sp 260 The following example illustrates the use of the \fB-p\fR option. 261 .sp 262 .in +2 263 .nf 264 # \fBsharemgr show -p mygroup\fR 265 default nfs=() 266 * /data/backup 267 mygroup nfs=(nosuid=true) 268 /export/home/home0 269 /export/home/home1 270 .fi 271 .in -2 272 .sp 273 274 The following example illustrates the use of the \fB-v\fR option. 275 .sp 276 .in +2 277 .nf 278 # \fBsharemgr show -v mygroup\fR 279 mygroup 280 HOME0=/export/home/home0 "Home directory set 0" 281 HOME1=/export/home/home1 "Home directory set 1" 282 .fi 283 .in -2 284 .sp 285 286 ZFS managed shares are handled in a way similar to the way NFS shares are 287 handled. These shares appear as subgroups within the parent group \fBzfs\fR. 288 The subgroups are always prefixed with \fBzfs/\fR and use the ZFS dataset name 289 for the rest of the name. The mount point and any sub-mounts that inherit 290 sharing are shown as the shares of the subgroup. For example: 291 .sp 292 .in +2 293 .nf 294 # \fBsharemgr show -vp zfs\fR 295 zfs nfs=() 296 zfs/ztest 297 /ztest 298 /ztest/backups 299 .fi 300 .in -2 301 .sp 302 303 .RE 304 305 .sp 306 .ne 2 307 .na 308 \fB\fBset\fR \fB[-nvh] -P \fIproto\fR [-S \fIoptionset\fR] [-p 309 \fIproperty\fR=\fIvalue\fR]* [-s \fIshare path\fR] \fIgroup\fR\fR\fR 310 .ad 311 .sp .6 312 .RS 4n 313 Set protocol-specific properties on the specified group. 314 .sp 315 The \fB-P\fR option is required and must specify a valid protocol. 316 .sp 317 Optionsets are protocol-specific sets of properties that can be negotiated by 318 the protocol client. For NFS, optionsets are equivalent to security modes as 319 defined in \fBnfssec\fR(5). If \fB-S\fR \fIoptionset\fR is specified, the 320 properties are applied to the selected optionset. Otherwise they are applied to 321 the general optionset. 322 .sp 323 Together, \fB-P\fR and \fB-S\fR select a specific view of the group's options 324 on which to work. 325 .sp 326 Property values are strings. A specified property is set to a new value if the 327 property already exists or is added to the protocol if it does not already 328 exist. 329 .sp 330 In the general case, at least one property must be set. If \fB-S\fR is 331 specified, properties can be omitted and the specified optionset is enabled for 332 the protocol. 333 .sp 334 The \fB-s\fR option allows setting properties on a per-share basis. While this 335 is supported, it should be limited to managing legacy shares and to the 336 occasional need for an override of a group-level property or placing an 337 additional property on one share within a group. 338 .sp 339 An example of this subcommand: 340 .sp 341 .in +2 342 .nf 343 # \fBsharemgr set -P nfs -p anon=1234 mygroup\fR 344 .fi 345 .in -2 346 .sp 347 348 The preceding command adds the property \fBanon=1234\fR to the \fBnfs\fR view 349 of group \fBmygroup\fR. If \fBmygroup\fR has existing shares, they will all be 350 reshared with the new property value(s). 351 .RE 352 353 .sp 354 .ne 2 355 .na 356 \fB\fBunset\fR \fB[-nvh] -P proto [-S \fIoptionset\fR] [-p \fIproperty\fR]* [-s 357 \fIsharepath\fR ] \fIgroup\fR\fR\fR 358 .ad 359 .sp .6 360 .RS 4n 361 Unset the specified properties for the protocol or for the specified 362 \fIoptionset\fR of the protocol. 363 .sp 364 In the general case, at least one property must be set. If \fB-S\fR is 365 specified, properties can be omitted and the specified optionset is removed 366 from the protocol. 367 .sp 368 The \fB-s\fR option allows removing a share-specific property. 369 .sp 370 An example of this subcommand: 371 .sp 372 .in +2 373 .nf 374 # \fBsharemgr unset -P nfs -p anon mygroup\fR 375 .fi 376 .in -2 377 .sp 378 379 The preceding command removes the \fBanon=\fR property from the \fBnfs\fR view 380 of group \fBmygroup\fR. If \fBmygroup\fR has existing shares, they will all be 381 reshared with the new property value(s). 382 .RE 383 384 .sp 385 .ne 2 386 .na 387 \fB\fBadd-share\fR \fB[-nth] [-r \fIresource-name\fR] [-d "\fIdescription 388 text\fR"] -s \fIsharepath\fR \fIgroup\fR\fR\fR 389 .ad 390 .sp .6 391 .RS 4n 392 Add a new share to the specified group. 393 .sp 394 The \fB-s\fR option is mandatory and takes a full directory path. 395 .sp 396 If either or both of \fB-d\fR and \fB-r\fR are specified, they specify values 397 associated with the share. \fB-d\fR provides a description string to document 398 the share and \fB-r\fR provides a protocol-independent resource name. Resource 399 names are not used by NFS at this time but can be specified. These names 400 currently follow the same naming rules as group names. 401 .sp 402 The temporary option (\fB-t\fR) results in the share being shared but not 403 stored in the configuration repository. This option is intended for shares that 404 should not survive a reboot or server restart, or for testing purposes. 405 Temporary shares are indicated in the \fBshow\fR subcommand output with an 406 asterisk (\fB*\fR) preceding the share. 407 .sp 408 If \fIsharepath\fR is a ZFS path and that path is added to the \fBzfs\fR group, 409 \fBsharemgr\fR creates a new ZFS subgroup; the new share is added to that 410 subgroup. Any ZFS sub-filesystems under the ZFS filesystem designated by 411 \fIsharepath\fR will inherit the shared status of \fIsharepath\fR. 412 .sp 413 The effect of the \fBadd-share\fR subcommand on a ZFS dataset is determined by 414 the values of the \fBsharesmb\fR and \fBsharenfs\fR properties of that dataset. 415 .sp 416 See \fBzfs\fR(1M) for a description of the \fBsharesmb\fR and \fBsharenfs\fR 417 properties. 418 .sp 419 The following are examples of the \fBadd-share\fR subcommand. 420 .sp 421 .in +2 422 .nf 423 # \fBsharemgr add-share -s /export/home/home0 -d "home \e 424 directory set 0" -r HOME0 mygroup\fR 425 426 # \fBsharemgr add-share -s /export/home/home1 -d "home \e 427 directory set 1" -r HOME1 mygroup\fR 428 .fi 429 .in -2 430 .sp 431 432 The preceding commands add \fB/export/home/home0\fR and 433 \fB/export/home/home1\fR to the group \fBmygroup\fR. A descriptive comment and 434 a resource name are included. 435 .RE 436 437 .sp 438 .ne 2 439 .na 440 \fB\fBmove-share\fR \fB[-nvh] -s \fIsharepath\fR \fIdestination-group\fR\fR\fR 441 .ad 442 .sp .6 443 .RS 4n 444 Move the specified share from the group it is currently in to the specified 445 destination group. The \fBmove-share\fR subcommand does not create a group. A 446 specified group must exist for the command to succeed. 447 .sp 448 The following is an example of this subcommand. 449 .sp 450 .in +2 451 .nf 452 # \fBsharemgr move-share -s /export/home/home1 newgroup\fR 453 .fi 454 .in -2 455 .sp 456 457 Assuming \fB/export/home/home1\fR is in the group \fBmygroup\fR, the preceding 458 command moves \fB/export/home/home1\fR to the group \fBnewgroup\fR and unshares 459 and then reshares the directory with the properties associated with 460 \fBnewgroup\fR. 461 .RE 462 463 .sp 464 .ne 2 465 .na 466 \fB\fBremove-share\fR \fB[-fnvh] -s \fIsharepath\fR \fIgroup\fR\fR\fR 467 .ad 468 .sp .6 469 .RS 4n 470 Remove the specified share from the specified group. The force (\fB-f\fR) 471 option forces the share to be removed even if it is busy. 472 .sp 473 You must specify the full path for \fIsharepath\fR. For group, use the subgroup 474 as displayed in the output of the \fBsharemgr show\fR command. Note that if 475 there are subshares that were created by inheritance, these will be removed, 476 along with the parent shares. 477 .RE 478 479 .sp 480 .ne 2 481 .na 482 \fB\fBset-share\fR \fB[-nvh] [-r \fIresource\fR] [-d "\fIdescription text\fR"] 483 -s \fIsharepath\fR \fIgroup\fR\fR\fR 484 .ad 485 .sp .6 486 .RS 4n 487 Set or change the specified share's description and resource values. One use of 488 \fBset-share\fR is to rename a resource. The syntax for this use of the 489 subcommand is: 490 .sp 491 .in +2 492 .nf 493 # \fBsharemgr set-share -r \fIcurrent_name\fR=\fInew_name\fR -s \fIsharepath\fR \fIgroup\fR\fR 494 .fi 495 .in -2 496 .sp 497 498 .RE 499 500 .sp 501 .ne 2 502 .na 503 \fB\fBenable\fR \fB[-nvh] [\fIgroup\fR... | -a]\fR\fR 504 .ad 505 .sp .6 506 .RS 4n 507 Enable the specified group(s), or (with \fB-a\fR) all groups, and start sharing 508 the contained shares. This state persists across reboots. 509 .sp 510 An enabled group will be shared whenever the corresponding SMF service instance 511 is enabled. \fBsharemgr\fR will start the SMF service instance if it is not 512 currently online. 513 .RE 514 515 .sp 516 .ne 2 517 .na 518 \fB\fBdisable\fR \fB[-nvh] [\fIgroup\fR... | -a]\fR\fR 519 .ad 520 .sp .6 521 .RS 4n 522 Disable the specified group(s), or (with \fB-a\fR) all groups, and unshare the 523 shares that they contain. This state persists across reboots. 524 .sp 525 A disabled group will not be shared even if the corresponding SMF service 526 instance is online. This feature is useful when you do not want a group of 527 shares to be started at boot time. 528 .RE 529 530 .sp 531 .ne 2 532 .na 533 \fB\fBstart\fR \fB[-vh] [-P \fIproto\fR] [\fIgroup\fR... | -a]\fR\fR 534 .ad 535 .sp .6 536 .RS 4n 537 Start the specified group, or (with \fB-a\fR) all groups. The \fBstart\fR 538 subcommand is similar to \fBenable\fR in that all shares are started, but 539 \fBstart\fR works only on groups that are enabled. \fBstart\fR is used by the 540 SMF to start sharing at system boot. 541 .sp 542 A group will not start sharing if it is in the \fBsharemgr\fR \fBdisabled\fR 543 state. However, the corresponding SMF service instance will be started. 544 .sp 545 Note that the \fBstart\fR subcommand is similar to the \fBshareall\fR(1M) 546 command in that it starts up only the configured shares. That is, the enabled 547 shares will start being shared, but the configuration state is left the same. 548 The command: 549 .sp 550 .in +2 551 .nf 552 # \fBsharemgr start -a\fR 553 .fi 554 .in -2 555 .sp 556 557 \&...is equivalent to: 558 .sp 559 .in +2 560 .nf 561 # \fBshareall\fR 562 .fi 563 .in -2 564 .sp 565 566 .RE 567 568 .sp 569 .ne 2 570 .na 571 \fB\fBstop\fR \fB[-vh] [-P \fIproto\fR] [\fIgroup\fR... | -a]\fR\fR 572 .ad 573 .sp .6 574 .RS 4n 575 Stop the specified group, or (with \fB-a\fR) all groups. The \fBstop\fR 576 subcommand is similar to \fBdisable\fR in that all shares are no longer shared, 577 but it works only on groups that are enabled. \fBstop\fR is used by the SMF to 578 stop sharing at system shutdown. 579 .sp 580 Note that the \fBstop\fR subcommand is similar to the \fBunshareall\fR(1M) 581 command in that all active shares are unshared, but the configuration is left 582 the same. That is, the shares are stopped but the service instances are left 583 enabled. The command: 584 .sp 585 .in +2 586 .nf 587 # \fBsharemgr stop -a\fR 588 .fi 589 .in -2 590 .sp 591 592 \&...is equivalent to: 593 .sp 594 .in +2 595 .nf 596 # \fBunshareall\fR 597 .fi 598 .in -2 599 .sp 600 601 .RE 602 603 .sp 604 .ne 2 605 .na 606 \fB\fBshare\fR \fB[-F \fIfstype\fR] [-p] [-o \fIoptionlist\fR] [-d 607 \fIdescription\fR] [\fIpathname\fR [\fIresourcename\fR]]\fR\fR 608 .ad 609 .sp .6 610 .RS 4n 611 Shares the specified path in the \fBdefault\fR share group. This subcommand 612 implements the \fBshare\fR(1M) functionality. Shares that are shared in this 613 manner will be transient shares. Use of the \fB-p\fR option causes the shares 614 to be persistent. 615 .RE 616 617 .sp 618 .ne 2 619 .na 620 \fB\fBunshare\fR \fB[-F \fIfstype\fR] [-p] [-o \fIoptionlist\fR] 621 \fIsharepath\fR\fR\fR 622 .ad 623 .sp .6 624 .RS 4n 625 Unshares the specified share. This subcommand implements the \fBunshare\fR(1M) 626 functionality. By default, the \fBunshare\fR is temporary. The \fB-p\fR option 627 is provided to remove the share from the configuration in a way that persists 628 across reboots. 629 .RE 630 631 .SH EXIT STATUS 632 .ne 2 633 .na 634 \fB\fB0\fR\fR 635 .ad 636 .RS 18n 637 Successful completion. 638 .RE 639 640 .sp 641 .ne 2 642 .na 643 \fB\fB98\fR\fR 644 .ad 645 .RS 18n 646 Service is offline and cannot be enabled (start only). 647 .RE 648 649 .sp 650 .ne 2 651 .na 652 \fB\fIother non-zero\fR\fR 653 .ad 654 .RS 18n 655 Command failed. 656 .RE 657 658 .SH FILES 659 .ne 2 660 .na 661 \fB\fB/usr/include/libshare.h\fR\fR 662 .ad 663 .RS 27n 664 Error codes used for exit status. 665 .RE 666 667 .SH ATTRIBUTES 668 .LP 669 See \fBattributes\fR(5) for descriptions of the following attributes: 670 .sp 671 672 .sp 673 .TS 674 box; 675 c | c 676 l | l . 677 ATTRIBUTE TYPE ATTRIBUTE VALUE 678 _ 679 Interface Stability Committed 680 .TE 681 682 .SH SEE ALSO 683 .LP 684 \fBidmap\fR(1M), \fBsharectl\fR(1M), \fBzfs\fR(1M), \fBattributes\fR(5), 685 \fBnfssec\fR(5), \fBshareacl\fR(5), \fBsharenfs\fR(5), \fBsharesmb\fR(5), 686 \fBsmf\fR(5), \fBstandards\fR(5)