System Administration Commands sharemgr(1M) NAME sharemgr - configure and manage file sharing SYNOPSIS sharemgr subcommand [options] add-share [-nth] [-r resource-name] [-d "description text"] -s sharepath_group create [-nvh] [-P proto [-p property=value]] group delete [-nvh] [-P proto] [-f] group disable [-nvh] [-a | group...] enable [-nvh] [-a | group...] list [-vh] [-P proto] move-share [-nv] -s sharepath destination-group remove-share [-fnvh] -s sharepath group set [-nvh] -P proto [-p property=value]... [-S optionset] [-s sharepath] group set-share [-nh] [-r resource] [-d "description text"] -s sharepath group show [-pvxh] [-P proto] [group]... unset [-nvh] -P proto [-S optionset] [-p property]... group share [-F fstype] [-p] [-o optionlist] [-d description] [pathname [resourcename]] unshare [-F fstype] [-p] [-o optionlist] sharepath DESCRIPTION The sharemgr command configures share groups and the shares contained within them. A group name must conform to service management facility (SMF) (see smf(5)) service-naming conventions, thus is lim- ited to starting with an alphabetic character, with the rest of the name consisting only of alphanumeric characters plus - (hyphen) and _ (underbar). SunOS 5.11 Last change: 13 Jul 2006 1 System Administration Commands sharemgr(1M) Subcommands that result in a configuration change support a dry-run option. When dry-run (-n) is specified, the syntax and validity of the command is tested but the configuration is not actually updated. For all subcommands, the -h option lists usage and help information. For subcommands with the verbose (-v) option, additional information will be provided. For example, in conjunction with the -n option, verbose will mode will also indicate whether the current user has sufficient permissions to accomplish the operation. There are two groups that are created automatically. The default group always exists and covers legacy shares. The zfs group will be created when ZFS shares are enabled. The options shown in the SYNOPSIS section are described in the context of each subcommand. All subcommands except list and show require root privileges or that you assume the Pri- mary Administrator role. Subcommands With no subcommand entered, a sharemgr command with the -h option displays a usage message for all subcommands. The following subcommands follow sharemgr on a command line. Commands take the form: % sharemgr [options] create [-nvh] [-P proto [-p property=value]] group Create a new group with specified name. SunOS 5.11 Last change: 13 Jul 2006 2 System Administration Commands sharemgr(1M) If -n is specified, the command checks only the validity of the command and that the group does not already exist. If no protocol is specified, all known protocols are enabled for the specified group. If a protocol is speci- fied, only that protocol is enabled. You can specify properties for a specified protocol. If group exists, use of -P adds the specified protocol to that group. As an example of the create subcommand, the following command creates a new group with the name mygroup. # sharemgr create mygroup Because no protocol was specified in the preceding com- mand, all defined protocols will be enabled on the group. delete [-nvh] [-P proto] [-f] group Delete the specified group. If the group is not empty, you can use the -f option to force the deletion, which unshares and removes all shares from the group before removing the group itself. If you specify a protocol, rather than deleting the whole group, this subcommand deletes the protocol from the group. The -n option can be used to test the syntax of the com- mand. SunOS 5.11 Last change: 13 Jul 2006 3 System Administration Commands sharemgr(1M) As an example, the following command removes the group mygroup from the configuration if it is empty. # sharemgr delete mygroup The following command removes any existing shares prior to removing the group. # sharemgr delete -f mygroup Note the use of the force (-f) option, above. list [-vh] [-P proto] List the defined groups. If a protocol is specified, list only those groups that have the specified protocol defined. If the verbose option is specified, the current state of the group and all protocols enabled on the group are listed as well. For example: # sharemgr list -v mygroup enabled nfs rdonlygrp disabled nfs show [-pvxh] [-P proto] [group...] Shows the contents of the specified group(s). SunOS 5.11 Last change: 13 Jul 2006 4 System Administration Commands sharemgr(1M) If the verbose option is specified, the resource name and description of each share is displayed if they are defined. Otherwise, only the share paths are displayed. Also, when temporary shares are listed, they are pre- fixed with an asterisk (*). If the -p option is specified, all options defined for the protocols of the group are displayed, in addition to the display without options. If the -P option is used, the output is limited to those groups that have the specified protocol enabled. If the -x option is speci- fied, output is in XML format and the -p and -v options are ignored, because all information is included in the XML. The following example illustrates the use of the -p option. # sharemgr show -p mygroup default nfs=() * /data/backup mygroup nfs=(nosuid=true) /export/home/home0 /export/home/home1 The following example illustrates the use of the -v option. # sharemgr show -v mygroup mygroup HOME0=/export/home/home0 "Home directory set 0" HOME1=/export/home/home1 "Home directory set 1" ZFS managed shares are handled in a way similar to the way NFS shares are handled. These shares appear as sub- groups within the parent group zfs. The subgroups are always prefixed with zfs/ and use the ZFS dataset name for the rest of the name. The mount point and any sub- mounts that inherit sharing are shown as the shares of the subgroup. For example: SunOS 5.11 Last change: 13 Jul 2006 5 System Administration Commands sharemgr(1M) # sharemgr show -vp zfs zfs nfs=() zfs/ztest /ztest /ztest/backups set [-nvh] -P proto [-S optionset] [-p property=value]* [-s share path] group Set protocol-specific properties on the specified group. The -P option is required and must specify a valid pro- tocol. Optionsets are protocol-specific sets of properties that can be negotiated by the protocol client. For NFS, optionsets are equivalent to security modes as defined in nfssec(5). If -S optionset is specified, the proper- ties are applied to the selected optionset. Otherwise they are applied to the general optionset. Together, -P and -S select a specific view of the group's options on which to work. Property values are strings. A specified property is set to a new value if the property already exists or is added to the protocol if it does not already exist. In the general case, at least one property must be set. If -S is specified, properties can be omitted and the specified optionset is enabled for the protocol. The -s option allows setting properties on a per-share basis. While this is supported, it should be limited to managing legacy shares and to the occasional need for an override of a group-level property or placing an SunOS 5.11 Last change: 13 Jul 2006 6 System Administration Commands sharemgr(1M) additional property on one share within a group. An example of this subcommand: # sharemgr set -P nfs -p anon=1234 mygroup The preceding command adds the property anon=1234 to the nfs view of group mygroup. If mygroup has existing shares, they will all be reshared with the new property value(s). unset [-nvh] -P proto [-S optionset] [-p property]* [-s sharepath ] group Unset the specified properties for the protocol or for the specified optionset of the protocol. In the general case, at least one property must be set. If -S is specified, properties can be omitted and the specified optionset is removed from the protocol. The -s option allows removing a share-specific property. An example of this subcommand: # sharemgr unset -P nfs -p anon mygroup The preceding command removes the anon= property from the nfs view of group mygroup. If mygroup has existing shares, they will all be reshared with the new property value(s). SunOS 5.11 Last change: 13 Jul 2006 7 System Administration Commands sharemgr(1M) add-share [-nth] [-r resource-name] [-d "description text"] -s sharepath group Add a new share to the specified group. The -s option is mandatory and takes a full directory path. If either or both of -d and -r are specified, they specify values associated with the share. -d provides a description string to document the share and -r provides a protocol-independent resource name. Resource names are not used by NFS at this time but can be specified. These names currently follow the same naming rules as group names. The temporary option (-t) results in the share being shared but not stored in the configuration repository. This option is intended for shares that should not sur- vive a reboot or server restart, or for testing pur- poses. Temporary shares are indicated in the show sub- command output with an asterisk (*) preceding the share. The following are examples of the add-share subcommand. # sharemgr add-share -s /export/home/home0 -d "home" \ directory set 0" -r HOME0 mygroup # sharemgr add-share -s /export/home/home1 -d "home" \ directory set 0" -r HOME1 mygroup The preceding commands add /export/home/home0 and /export/home/home1 to the group mygroup. A descriptive comment and a resource name are included. move-share [-nvh] -s sharepath destination-group SunOS 5.11 Last change: 13 Jul 2006 8 System Administration Commands sharemgr(1M) Move the specified share from the group it is currently in to the specified destination group. The move-share subcommand does not create a group. A specified group must exist for the command to succeed. The following is an example of this subcommand. # sharemgr move-share -s /export/home/home1 newgroup Assuming /export/home/home1 is in the group mygroup, the preceding command moves /export/home/home1 to the group newgroup and unshares and then reshares the directory with the properties associated with newgroup. remove-share [-fnvh] -s sharepath group Remove the specified share from the specified group. The force (-f) option forces the share to be removed even if it is busy. set-share [-nvh] [-r resource] [-d "description text"] -s sharepath group Set or change the specified share's description and resource values. enable [-nvh] [group... | -a] Enable the specified group(s), or (with -a) all groups, and start sharing the contained shares. This state per- sists across reboots. An enabled group will be shared whenever the SunOS 5.11 Last change: 13 Jul 2006 9 System Administration Commands sharemgr(1M) corresponding SMF service instance is enabled. sharemgr will start the SMF service instance if it is not currently online. disable [-nvh] [group... | -a] Disable the specified group(s), or (with -a) all groups, and unshare the shares that they contain. This state persists across reboots. A disabled group will not be shared even if the corresponding SMF service instance is online. This feature is useful when you do not want a group of shares to be started at boot time. start [-vh] [-P proto] [group... | -a] Start the specified group, or (with -a) all groups. The start subcommand is similar to enable in that all shares are started, but start works only on groups that are enabled. start is used by the SMF to start sharing at system boot. A group will not start sharing if it is in the sharemgr disabled state. However, the corresponding SMF service instance will be started. Note that the start subcommand is similar to the shareall(1M) command in that it starts up only the con- figured shares. That is, the enabled shares will start being shared, but the configuration state is left the same. The command: # sharemgr start -a SunOS 5.11 Last change: 13 Jul 2006 10 System Administration Commands sharemgr(1M) ...is equivalent to: # shareall stop [-vh] [-P proto] [group... | -a] Stop the specified group, or (with -a) all groups. The stop subcommand is similar to disable in that all shares are no longer shared, but it works only on groups that are enabled. stop is used by the SMF to stop sharing at system shutdown. Note that the stop subcommand is similar to the unshareall(1M) command in that all active shares are unshared, but the configuration is left the same. That is, the shares are stopped but the service instances are left enabled. The command: # sharemgr stop -a ...is equivalent to: # unshareall share [-F fstype] [-p] [-o optionlist] [-d description] [pathname [resourcename]] Shares the specified path in the default share group. This subcommand implements the share(1M) functionality. Shares that are shared in this manner will be transient shares. Use of the -p option causes the shares to be persistent. SunOS 5.11 Last change: 13 Jul 2006 11 System Administration Commands sharemgr(1M) unshare [-F fstype] [-p] [-o optionlist] sharepath Unshares the specified share. This subcommand implements the unshare(1M) functionality. By default, the unshare is temporary. The -p option is provided to remove the share from the configuration in a way that persists across reboots. Supported Properties Properties are protocol-specific. Currently, only the NFS protocol is supported. Properties have the following charac- teristics: o Values of type boolean take either true or false. o Values of type value take a numeric value. o Values of type file take a file name and not a file path. o Values of type access-list are described in detail following the descriptions of the NFS properties. The general properties supported for NFS are: aclok=boolean SunOS 5.11 Last change: 13 Jul 2006 12 System Administration Commands sharemgr(1M) Allows the NFS server to do access control for NFS Ver- sion 2 clients (running SunOS 2.4 or earlier). When aclok is set on the server, maximum access is given to all clients. For example, with aclok set, if anyone has read permissions, then everyone does. If aclok is not set, minimum access is given to all clients. anon=uid Set uid to be the effective user ID of unknown users. By default, unknown users are given the effective user ID UID_NOBODY. If uid is set to -1, access is denied. cksum=cksumlist Set the share to attempt to use end-to-end checksums. The value cksumlist specifies the checksum algorithms that should be used. index=file Load file rather than a listing of the directory con- taining this file when the directory is referenced by an NFS URL. log=tag Enables NFS server logging for the specified system. The optional tag determines the location of the related log files. The tag is defined in etc/nfs/nfslog.conf. If no tag is specified, the default values associated with the global tag in etc/nfs/nfslog.conf is used. Support of NFS server logging is available only for NFS Version 2 and Version 3 requests. SunOS 5.11 Last change: 13 Jul 2006 13 System Administration Commands sharemgr(1M) nosub=boolean Prevents clients from mounting subdirectories of shared directories. For example, if /export is shared with the nosub option on server wool then an NFS client cannot do: # mount -F nfs wool:/export/home/mnt NFS Version 4 does not use the MOUNT protocol. The nosub option applies only to NFS Version 2 and Version 3 requests. nosuid=boolean By default, clients are allowed to create files on a shared file system with the setuid or setgid mode enabled. Specifying nosuid causes the server file system to silently ignore any attempt to enable the setuid or setgid mode bits. public=boolean Moves the location of the public file handle from root (/) to the exported directory for WebNFS-enabled browsers and clients. This option does not enable WebNFS service; WebNFS is always on. Only one file system per server can have the public property. You can apply the public property only to a share and not to a group. + NFS provides support to convert the character set used by + some clients to UTF-8 on the server. The specific conver- + sions available depend on what is installed on the server. + The list of supported conversions is documented in + kiconv_open(9). The conversions are used when a server + should maintain all file/directory names in UTF-8 but some + clients do not send requests with a suitable character set. + The property is the lowercase version of the SunOS 5.11 Last change: 13 Jul 2006 14 System Administration Commands sharemgr(1M) + documented names. General specification is: is: + =access-list NFS also supports negotiated optionsets for supported security modes. The security modes are documented in nfssec(5). The properties supported for these optionsets are: ro=access-list Sharing is read-only to the clients listed in access-list; overrides the rw suboption for the clients specified. See the description of access- list below. + none=access-list + Clients listed in access-list are prevented from + accessing the share. See the description of + access-list below. rw=access-list Sharing is read-write to the clients listed in access-list; overrides the ro suboption for the clients specified. See the description of access- list below. root=access-list Sharing is read-only to the clients listed in access-list; overrides the rw suboption for the clients specified. See the description of access- list below. SunOS 5.11 Last change: 13 Jul 2006 15 System Administration Commands sharemgr(1M) + root_mapping=uid + Root users allowed access via the root option will + have their user id mapped to uid rather than 0. window=value When sharing with sec=dh (see nfssec(5)), set the maximum lifetime (in seconds) of the RPC request's credential (in the authentication header) that the NFS server allows. If a credential arrives with a lifetime larger than what is allowed, the NFS server rejects the request. The default value is 30000 seconds (8.3 hours). This property is ignored for security modes other than dh. The access-list argument is either the string "*" to represent all hosts or a colon-separated list whose com- ponents can be any number of the following: hostname The name of a host. With a server configured for DNS or LDAP naming in the nsswitch.conf(4) hosts entry, a hostname must be represented as a fully qualified DNS or LDAP name. netgroup A netgroup contains a number of hostnames. With a server configured for DNS or LDAP naming in the nsswitch.conf(4) hosts entry, any hostname in a net- group must be represented as a fully qualified DNS or LDAP name. SunOS 5.11 Last change: 13 Jul 2006 16 System Administration Commands sharemgr(1M) domainname.suffix To use domain membership the server must use DNS or LDAP, rather than, for example, NIS or NIS+, to resolve hostnames to IP addresses. That is, the hosts entry in the nsswitch.conf(4) must specify dns or ldap ahead of nis or nisplus, because only DNS and LDAP return the full domain name of the host. Other name services, such as NIS or NIS+, cannot be used to resolve hostnames on the server because, when mapping an IP address to a hostname, they do not return domain information. For example, for the IP address 172.16.45.9: NIS or NIS+ Returns: myhost DNS or LDAP Returns: myhost.mydomain.mycompany.com The domain name suffix is distinguished from host- names and netgroups by a prefixed dot. For example: rw=.mydomain.mycompany.com A single dot can be used to match a hostname with no suffix. For example, the specification: rw=. ...matches mydomain but not mydomain.mycompany.com. This feature can be used to match hosts resolved through NIS and NIS+ rather than DNS and LDAP. SunOS 5.11 Last change: 13 Jul 2006 17 System Administration Commands sharemgr(1M) network The network or subnet component is preceded by an at-sign (@). It can be either a name or a dotted address. If a name, it is converted to a dotted address by getnetbyname(3SOCKET). For example: =@mynet ...is equivalent to: =@172.16 or =@172.16.0.0 The network prefix assumes an octet-aligned netmask determined from the zero octets in the low-order part of the address. In the case where network pre- fixes are not byte-aligned, the syntax allows a mask length to be specified explicitly following a slash (/) delimiter. For example: =@theothernet/17 or =@172.16.132/22 ...where the mask is the number of leftmost contigu- ous significant bits in the corresponding IP address. A prefixed minus sign (-) denies access to a component of access-list. The list is searched sequentially until a match is found that either grants or denies access, or until the end of the list is reached. For example, if host terra is in the netgroup engineering, then: rw=-terra:engineering ...denies access to terra, but: SunOS 5.11 Last change: 13 Jul 2006 18 System Administration Commands sharemgr(1M) rw=engineering:-terra ...grants access to terra. EXIT STATUS 0 Successful completion. 98 Service is offline and cannot be enabled (start only). other non-zero Command failed. FILES /usr/include/libshare.h Error codes used for exit status. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsu | |_____________________________|_____________________________| | Interface Stability | Evolving | |_____________________________|_____________________________| SEE ALSO sharectl(1M), attributes(5), nfssec(5), smf(5), standards(5) SunOS 5.11 Last change: 13 Jul 2006 19