sharemgr Command

The Solaris Express, Developer Edition 2/07 release includes the sharemgr utility, which is an administrative tool that provides an enhanced method of sharing files and performing related tasks. Previously, such tasks were accomplished by adding entries to the /etc/dfs/dfstab file and using the share command to create a temporary share. You made the share permanent by rebooting the system or using the shareall command. Related administrative tasks necessitated that you manually edit configuration files. The sharemgr utility simplifies this process by introducing two concepts:

• Share – One or more files or directories in a share group.

• Share group – A container of one or more shared files or directories. Note the following:

  • Options for sharemgr are set to a share group, not to a specific file or directory. All options apply to each file and directory in the group.

  • A file or directory can only be assigned to one share group. However, you can move a file or directory from one group to another.

  • A share group can be used by multiple file-system types. For example, the share group my_group could be used by NFS and ZFS and be assigned one set of options for NFS and another set of options for ZFS.

    ---

    Note –

    When a share is managed by ZFS, sharemgr identifies the share and lists it in a zfs share group.

    ---

The sharemgr utility accomplishes different tasks by using subcommands. Options and their related properties can be used with each subcommand. The utility uses the following syntax:

# sharemgr [subcommand] [option] [share_group]

The sharemgr utility provides a unique way of checking the validity of a desired configuration. The -n option allows you to test the validity of the options and properties you want to use with a specific subcommand. The test does not change your configuration. For example, if you use the -n option with the subcommand create, no share group is created.

The following tables describes the subcommands supported by the sharemgr utility.

The following table describes the properties supported by the sharemgr utility.

sharemgr and sharectl are the preferred utilities for managing your file systems and file-sharing protocols.

For procedures that use the sharemgr utility, see the following:

• Automatic File-System Sharing

• Mounting File Systems

• Administering the Secure NFS System

Also, see the sharemgr(1M) man page.

The sharectl utility is an administrative tool that enables you to configure and manage file-sharing protocols, such as NFS. For more information, see the following:

• sharectl(1M) man page

• sharectl Command.

The sections that follow describe each subcommand for sharemgr and provide examples.

• create Subcommand

• delete Subcommand

• list Subcommand

• show Subcommand

• set Subcommand

• unset Subcommand

• add-share Subcommand

• move-share Subcommand

• remove-share Subcommand

• set-share Subcommand

• enable Subcommand

• disable Subcommand

• start Subcommand

• stop Subcommand

• -h Feature

create Subcommand

The create subcommand makes (or creates) a share group. After you create a share group, use the add-share subcommand to add shares to the group. Note the following:

• The group name is restricted to alphanumeric characters, the hyphen (-), and the underscore (_). The first character must be alphabetic.

• By default, a newly created share group is enabled.

• If a file-system type is not specified, all supported protocols are added to the share group.

• When adding options to the share group, you must explicitly define the protocol associated with the options.

This subcommand supports the following options:

-n

Checks the validity of a desired configuration.

-P

Specifies a file-system type. The default is NFS.

-p

Specifies a property for the new share group.

-h

Provides an online-help description.

The create subcommand uses the following syntax:

# sharemgr create [-h] [-n] [-P protocol] [-p property=value] share_group

The following example creates my_group with the following parameters:

• The share group uses NFS.

• The permissions for the group are set to read-write.

• The functions, setuid() and setgid(), cannot be used on my_group.

example# sharemgr create -P nfs -p rw=true -p nosuid=true my_group

delete Subcommand

This subcommand removes a share group. Before using this option, use the remove-share subcommand to delete all shares from the group. Alternately, use the -f option with this subcommand to force the removal of a group that might still contain shares. The -f option unshares and removes all shares from the share group, so the share group can be removed.

To remove a protocol from a share group, use the -P option. Note that when using the -P option, the share group is not removed. Only the protocol is removed from the group.

This subcommand supports the following options:

-n

Checks the validity of command-line string

-f

Forces a share group to be removed

-P

Specifies a file-system type to be removed from the group

-h

Provides an online-help description

This subcommand uses the following syntax:

# sharemgr delete [-h] [-n] [-f] [-P protocol] share_group

list Subcommand

This subcommand provides a list of current share groups. You can customize the output by using various options with this subcommand.

This subcommand supports the following options:

-P

Enables you to see a list of groups that use a specific file-system type.

-v

Is the verbose option and provides the following:

• Group name

• Status of the group, specifically whether the group is enabled or disabled

• File-system type used by the group

-h

Provides an online-help description.

This subcommand uses the following syntax:

# sharemgr list [-h] [-P protocol] [-v]

The following example shows the output for the -v option:

example# sharemgr list -v
group01   enabled    nfs
group02   disabled   nfs

show Subcommand

This subcommand provides a list of shares by group. By specifying one or more share groups, you can limit the output to a list of shares in the specified groups. If no groups are specified, the list shows the shares in each group.

This subcommand supports the following options:

-p

Shows you the properties assigned to each group.

-v

Is the verbose option. If included, the verbose option provides the resource name and descriptions of each share.

-x

Creates an XML file for the output. Because this option automatically includes the information you would get from the -p and -v options, no other options are needed when you use this option.

-h

Provides an online-help description.

This subcommand uses the following syntax:

# sharemgr show [-h] [-v] [-p] [-x] [share_group...]

The following example uses the -p option to show the shares and group properties for my_group:

example01# sharemgr show -p my_group
my_group	nfs=(rw=true nosuid=true)
	/export/home/home0
	/export/home/home1

The next example uses the -v option to show the shares in my_group and their descriptions:

example02# sharemgr show -v my_group
my_group
	HOME0=/export/home/home0	"Home directory set 0"
	HOME1=/export/home/home1	"Home directory set 1"

set Subcommand

This subcommand sets properties to a share group. Note the following conditions:

• If you do not change the protocol currently associated with the group, the previous property value is replaced with the new value.

• If you specify a different protocol for the group, the new properties for the different protocol are added to the existing shares.

A group can be associated with more than one protocol and can have different properties for each protocol.

This subcommand supports the following options:

-n

Checks the validity of the command-line string.

-P

Specifies a file-system type.

-p

Specifies a property for the share group.

-S

Specifies the security mode, such as sys, dh, or krb5. For more information about security modes, see the nfssec(5) man page.

-s

Specifies the path to the share, which is a file or a directory.

-h

Provides an online-help description.

This subcommand uses the following syntax:

# sharemgr set [-h] [-n] [-P protocol] [-s share-path] [-S security-mode] [-p property=value] share_group

The following example sets the user ID for unknown users in my_group to 1234546:

example01# sharemgr set -p anon=123456 my_group

In the next example, the following occurs:

• my_group continues to use NFS.

• Previously, nosuid was set to true. Because set replaces the previous value for nosuid with the new value, the functions, setuid() and setgid(), can now be used on the shares in my_group.

• The permissions for the group continue to be set to read-write.

example02# sharemgr create -P nfs -p rw=true -p nosuid=true my_group	
example02# sharemgr set -P nfs -p nosuid=false my_group

unset Subcommand

This subcommand removes (or unsets) properties from a share group.

This subcommand supports the following options:

-n

Checks the validity of the command-line string

-P

Specifies the protocol associated with the properties being removed from the group

-p

Specifies the property to be removed from the share group

-s

Specifies the path to the share, which is a file or a directory.

-h

Provides an online-help description

This subcommand uses the following syntax:

# sharemgr unset [-h] [-n] -P protocol [-s share-path] [-p property] share_group

add-share Subcommand

After creating a share group, use this subcommand to add shares to the group. A share is a path to a file or a directory. Note that a share can exist in one group only. If you try to add a share to another group, you will get an error message.

This subcommand supports the following options:

-n

Checks the validity of the command-line string.

-s

Specifies the path to the share, which is a file or a directory.

-t

Specifies that the share is transient. Transient shares are automatically removed from the group when you reboot the system or use the disable or stop subcommands.

-d

Adds descriptive text about the share.

-r

Assigns the share a resource name that identifies the share. Note that the resource name only uses alphanumeric characters, the hyphen (-), and the underscore (_). The first character in the name must be alphabetic.

-h

Provides an online-help description.

This subcommand uses the following syntax:

# sharemgr add-share [-h] [-n] -s share-path [-t] [-d description] [-r resource-name] share_group

The following example adds the shares /export/home/home0 and /export/home/home1 to my_group.

example# sharemgr add-share -s /export/home/home0 my_group
example# sharemgr add-share -s /export/home/home1 my_group

move-share Subcommand

Use this subcommand to move a share from one group to another.

This subcommand supports the following options:

-n

Checks the validity of the command-line string

-s

Specifies the path to the share, which is a file or a directory

-h

Provides an online-help description

This subcommand uses the following syntax:

# sharemgr move-share [-h] [-n] -s share-path share_group

The following example shows a share that was added to my_group and then moved to your_group.

example# sharemgr add-share  -s /export/home/home0 my_group
example# sharemgr move-share -s /export/home/home0 your_group

remove-share Subcommand

Use this subcommand to remove a share from a share group.

This subcommand supports the following options:

-n

Checks the validity of the command-line string

-s

Specifies the path to the share, which is a file or a directory

-h

Provides an online-help description

This subcommand uses the following syntax:

# sharemgr remove-share [-h] [-n] -s share-path share_group

The following example removes the share /export/home/home0 from my_group.

example# sharemgr remove-share -s /export/home/home0 my_group

set-share Subcommand

Use this subcommand to change the properties associated with a share. Currently, you can use this subcommand to change the descriptive text associated with a specific share.

This subcommand supports the following options:

-n

Checks the validity of the command-line string.

-s

Specifies the path to the share, which is a file or a directory.

-d

Adds descriptive text about the share.

-r

Assigns the share a resource name that identifies the share. Note that the resource name only uses alphanumeric characters, the hyphen (-), and the underscore (_). The first character in the name must be alphabetic.

-h

Provides an online-help description.

This subcommand uses the following syntax:

# sharemgr set-share [-h] [-n] -s share-path [-d description] [-r resource-name] share_group

The following example shows how a description is changed.

example# sharemgr add-share  -s /export/home/home0 -d "original text" my_group
example# sharemgr set-share  -s /export/home/home0 -d "new text" my_group

enable Subcommand

Use this subcommand to share (or enable) the shares in the groups that you specify. Note that the groups you create are enabled by default. You must use this subcommand to enable a group that has previously been disabled with the disable subcommand.

If you specify a protocol, only the groups that are associated with that protocol are enabled.

This subcommand supports the following options:

-a

Specifies all groups

-n

Checks the validity of the command-line string

-P

Specifies a file-system type

-h

Provides an online-help description

This subcommand uses the following syntax:

# sharemgr enable [-h] [-n] [-P protocol] [share_group | -a]

The following example shares (or enables) the shares in all groups that use NFS.

example01# sharemgr enable -P NFS -a

In this next example, all shares in my_group are shared (or enabled).

example02# sharemgr enable my_group

disable Subcommand

Use this subcommand to unshare (or disable) the shares in the groups that you specify. This subcommand can be reversed by using the enable subcommand.

If you specify a protocol, only the groups that are associated with that protocol are disabled.

This subcommand supports the following options:

-a

Specifies all groups

-n

Checks the validity of the command-line string

-P

Specifies a file-system type

-h

Provides an online-help description

This subcommand uses the following syntax:

# sharemgr disable [-h] [-P protocol] [share_group | -a]

The following example unshares (or disables) the shares in all groups that use NFS.

example01# sharemgr disable -P NFS -a

In this next example, all shares in my_group are unshared (or disabled).

example02# sharemgr disable my_group

start Subcommand

This subcommand is similar to the enable subcommand with these distinctions:

• start enables the shares to start sharing in specified groups that have previously been stopped by the stop subcommand.

• start can be used by SMF (Service Management Facility) to enable shares to start sharing in specified groups during a system boot. See the man pages for smf(5) and svcadm(1M).

• start works only on groups that are enabled.

This subcommand supports the following options:

-a

Specifies all groups

-h

Provides an online-help description

# sharemgr start [-h] [share-group | -a]

# sharemgr start -a

# svcadm start network/shares/group:share-group

# svcadm start network/shares/group:my-group

stop Subcommand

This subcommand is similar to the disable subcommand with these distinctions:

• stop unshares the shares in specified groups, and can only be reversed by using the start subcommand.

• stop can be used by SMF (Service Management Facility) to unshare the shares in specified groups during a system shutdown. See the man pages for smf(5) and svcadm(1M).

• stop works only on groups that are enabled.

• stop permanently removes all transient shares.

This subcommand supports the following options:

-a

Specifies all groups

-h

Provides an online-help description

# sharemgr stop [-h] [share-group | -a]

# sharemgr stop -a

# svcadm stop network/shares/group:share-group

# svcadm stop network/shares/group:my-group

-h Feature

The sharemgr utility has an online help feature that describes sharemgr and its subcommands and options, and shows proper syntax. For online help, use -h.

This feature uses the following syntax:

# sharemgr [subcommand] -h

The following example uses -h to provide a complete description of the sharemgr utility.

example01# sharemgr -h
USAGE: # sharemgr [subcommand] [option] [share_group]

DESCRIPTION: Configures and manages file sharing

SUBCOMMANDS:
create        Makes (or creates) a new share group
delete        Removes a share group
list          Lists the current share groups
show          Lists the shares by share group
set           Sets a share group's properties
unset         Removes (or unsets) properties from a share group
add-share     Adds a new share to a share group
move-share    Moves a share from one share group to another
remove-share  Removes a share from a share group
set-share     Updates the properties associated with a share
disable       Unshares one or more share groups
enable        Shares one or more share groups
start         Used by the smf utility to share one or more share groups
stop          Used by the smf utility to unshare one or more share groups
-h            Online-help feature

SEE ALSO:
sharemgr(1M) man page
System Administration Guide: Network Services

This next example uses -h to provide information about the set subcommand.

example02# sharemgr set -h
USAGE: # sharemgr set [-h] [-n] [-P protocol] [-S security-mode] [-p property=value] share_group

DESCRIPTION: Sets a share group's properties

OPTIONS:
-h  Online-help feature
-n  Checks the validity of the command-line string
-P  Specifies a file-system type.
-p  Specifies a property for the share group.
-S  Specifies the security mode, such as sys, dh, or krb5

PROPERTIES:
aclok={true|false}        Enable access control lists (ACL) for NFS version 2.
anon=UID                  Specify the User ID for unknown users.
index=file path           Include the specified file in a content list for a directory.
log=tag                   Specify a tag to use for log messages.
nosub={true|false}        Disallow clients from mounting subdirectories of shares.
nosuid={true|false}       Disallow the use of the setuid() and setgid() functions.
ro={access-list|true|*}   If ro is set to an access-list, permissions for the list
                          are read-only. If ro is set to no value or to true, 
                          permissions for the share group are read-only. If ro
                          is set to an asterisk (*), permissions for all hosts
                          are set to read-only.
root={access-list|*}      If root  is set to an access-list, permissions for the
                          list are set to allow root access. If root is set to
                          an asterisk (*), all hosts have root access.
rw={access-list|true|*}   If rw is set to an access list, permissions for the list
                          are set to read-write. If rw is set to no value or to 
                          true, permissions for the share group are set to 
                          read-write. If rw is set to an asterisk (*), permissions
                          for all hosts are set to read-write.
window=integer            For the dh security mode, set the number of seconds a
                          credential is available.

SEE ALSO:
sharemgr(1M) man page
System Administration Guide: Network Services
nfssec(5) man page for more information about security modes

For help, you can also refer to the sharemgr(1M) man page.