samsharefs(1M)

NAME
     samsharefs - Manipulates the Sun QFS shared file system
     configuration

SYNOPSIS
     samsharefs [-f host] [-h] [-o host] [-q] [-R] [-s host] [-u]
     fs_name

AVAILABILITY
     SUNWsamfs
     SUNWqfs

DESCRIPTION
     The samsharefs command prints and modifies the host
     configuration for a Sun QFS shared file system.  The printed
     hosts configuration identifies the metadata server and the
     client hosts included in the Sun QFS shared file system.
     This command is only valid from the metadata server or
     potential metadata server.

     You create an initial hosts configuration file using vi(1)
     or another text editor.  The sammkfs(1M) command reads this
     initial hosts configuration from
     /etc/opt/SUNWsamfs/hosts.fs_name when the SAM-QFS shared
     file system is created.

     To subsequently change the host configuration you must use
     the samsharefs command.  Typically, you use an editor to
     edit the ASCII hosts configuration as printed by the
     samsharefs command and use the samsharefs command to update
     the file system host configuration.

OPTIONS
     This command accepts the following options:

     -f host   Marks host "off" in the hosts file.  This option
               rewrites the on-disk hosts file and causes the
               SAM-QFS daemon to reread the hosts file.  Marking
               the host off disallows that host to access the
               specified fs_name, and is reversed by using the -o
               option.  -f is incompatible with -u parameter.

               Marking a host client "off" allows that client to
               remain in the host file, but not access the
               specified file system.  It is intended to be used
               to remove clients and not require the file system
               to be unmounted on all other clients.  The removed
               host remains in the host file as a placeholder and
               can later be restored by using the -o parameter.
               Note that the client will need to be marked "off"
               from the metadata server for each file system that
               it mounts.

               The host client's "on" or "off" status can be seen
               in the 4th column of the host file (as printed by
               the samsharefs command).  For backwards
               compatibility, a "-", "0", or blank in this column
               indicates "on".  Also, if a client is marked off,
               it is indicated by an "OFF" flag on the samu "g"
               display (or the samcmd g command).

               CAUTIONS & LIMITATIONS:  A file system that is to
               be shared to other clients must be mounted on the
               metadata server and also be mountable to potential
               metadata servers.  Thus a client that is an actual
               metadata server cannot be marked off.

               The only supported way to mark a client host off
               is to unmount its file systems and shutdown and
               halt the client.  Then issue the samsharefs -f
               host fs command from the metadata server.

               The only supported way to restore a client host is
               to mark the client host on (using the -o
               parameter) prior to booting that client.  The
               client is then free to remount the affected file
               system.

               Clients, while marked off, will not be able to
               contact the metadata server for that file system.
               If a marked-off client tries to contact the
               metadata server for that file system, its messages
               will be discarded and system hangs may occur.  The
               result of trying to talk to a metadata server from
               a marked-off client is undefined and not
               supported.

     -h        Writes a short usage message to stdout.

     -o host   Marks host "on" in the hosts file.  This option
               rewrites the on-disk hosts file and causes the
               SAM-QFS daemon to reread the hosts file.  Marking
               the host on allows that host to access to the
               specified fs_name, and reverses the effect of the
               -f option.  -o is incompatible with -u parameter.
               See -f option above for cautions & limitations.

     -q        Suppresses host configuration output.  By default,
               the command writes the file system host
               configuration, possibly modified, to stdout.

     -R        Specifies that the file system's host
               configuration should be manipulated using the raw
               disk device associated with the file system,
               rather than the file system interfaces.  This
               option can be used to change hosts information
               when the file system is not or cannot be mounted.
               This option can also be used to change hosts
               information when the file system is mounted, but
               the active metadata server is down.

               CAUTION:  This option must not be executed on a
               potential metadata server to change the metadata
               server host without first stopping, disabling, or
               disconnecting the active metadata server.  Doing
               so will cause file system corruption.

     -s host   Sets the server flag for the specified host in the
               system configuration.  This option declares host
               to be the new metadata server host.  All other
               hosts's server flags are cleared.

     -u        Specifies that the file system's configuration is
               to be updated from
               /etc/opt/SUNWsamfs/hosts.fs_name.  When updating
               the configuration of a mounted file system, new
               host entries can only be added to the end of the
               existing configuration.  If the server or any
               host's position differs between hosts.fs_name and
               the active configuration (i.e., the order of the
               hosts is changed), the command issues an error
               message and exits; changing these characteristics
               can be done safely only on an idle, unmounted file
               system.  (See the -R option.)

     fs_name   Specifies the family set name of the Sun QFS
               shared file system.

EXAMPLES
     Example 1.  The following example shows how to use the
     samsharefs to examine the hosts information on a mounted Sun
     QFS shared file system:

     tethys# samsharefs share1
     #
     # Host file for family set 'share1'
     #
     # Version: 4    Generation: 14    Count: 3
     # Server = host 0/titan, length = 112
     #
     titan titan.xyzco.com 1 0
     tethys tethys.xyzco.com 2 0
     mimas mimas.xyzco.com 0 0

     Example 2.  The following example shows how the hosts
     configuration can be modified to add new hosts to the shared
     file system.  The administrator has edited
     /etc/opt/SUNWsamfs/hosts.share1 and added new hosts for the
     shared file system as shown.  samsharefs is then run with
     the -u option to update the (mounted) file system's
     configuration.

     titan# samsharefs share1
     #
     # Host file for family set 'share1'
     #
     # Version: 4    Generation: 14    Count: 3
     # Server = host 0/titan, length = 112
     #
     titan titan.xyzco.com 1 0
     tethys tethys.xyzco.com 2 0
     mimas mimas.xyzco.com 0 0

     titan# cat /etc/opt/SUNWsamfs/hosts.share1
     #
     # New share1 config, adds dione and rhea
     #
     titan   titan.xyzco.com 1 0 server
     tethys tethys.xyzco.com 2 0
     mimas   mimas.xyzco.com 0 0
     dione   dione.xyzco.com 0 0
     rhea     rhea.xyzco.com 0 0

     titan# samsharefs -u share1
     #
     # Host file for family set 'share1'
     #
     # Version: 4    Generation: 15    Count: 5
     # Server = host 0/titan, length = 162
     #
     titan titan.xyzco.com 1 0
     tethys tethys.xyzco.com 2 0
     mimas mimas.xyzco.com 0 0
     dione dione.xyzco.com 0 0
     rhea rhea.xyzco.com 0 0

     Example 3.  The following example shows how the hosts
     configuration can be modified to change the Sun QFS shared
     file system server while the file system is mounted.

     tethys# samsharefs -s tethys share1
     #
     # Host file for family set 'share1'
     #
     # Version: 4    Generation: 16    Count: 5
     # Server = host 0/titan, length = 162
     # Pending Server = host 1/tethys
     #
     titan titan.xyzco.com 1 0
     tethys tethys.xyzco.com 2 0
     mimas mimas.xyzco.com 0 0
     dione dione.xyzco.com 0 0
     rhea rhea.xyzco.com 0 0

     Example 4.  The following example shows how the hosts
     configuration can be modified to add a new Sun QFS shared
     file system server.  Because the new server's entry is being
     inserted into the existing list rather than appended to the
     end, the file system must be unmounted on all hosts before
     executing this command, and the -R option must be specified.
     Note also that this command changes the file system server
     back to titan (from tethys).

     tethys# samsharefs -R share1
     #
     # Host file for family set 'share1'
     #
     # Version: 4    Generation: 17    Count: 5
     # Server = host 1/tethys, length = 162
     #
     titan titan.xyzco.com 1 0
     tethys tethys.xyzco.com 2 0
     mimas mimas.xyzco.com 0 0
     dione dione.xyzco.com 0 0
     rhea rhea.xyzco.com 0 0

     tethys# cat /etc/opt/SUNWsamfs/hosts.share1
     #
     # New share1 config, adds server iapetus
     #
     titan     titan.xyzco.com 1 0 server
     tethys   tethys.xyzco.com 2 0
     iapetus iapetus.xyzco.com 3 0
     mimas     mimas.xyzco.com 0 0
     dione     dione.xyzco.com 0 0
     rhea       rhea.xyzco.com 0 0

     tethys# samsharefs -u -R share1
     #
     # Host file for family set 'share1'
     #
     # Version: 4    Generation: 18    Count: 6
     # Server = host 0/titan, length = 192
     #
     titan titan.xyzco.com 1 0
     tethys tethys.xyzco.com 2 0
     iapetus iapetus.xyzco.com 3 0
     mimas mimas.xyzco.com 0 0
     dione dione.xyzco.com 0 0
     rhea rhea.xyzco.com 0 0

FILES
     The hosts configuration for a Sun QFS shared file system is
     initialized from:

     /etc/opt/SUNWsamfs/hosts.fs_name

     This file is used at the time of file system creation by
     sammkfs(1M) and subsequently when the -u option is specified
     to samsharefs(1M).

NOTE
     In SAM-QFS shared file system environments, archiving
     operations should be stopped on the metadata server before
     changing the metadata server.

CAUTION
     The -R option must not be used on a mounted file system to
     change the metadata server host without first stopping,
     disabling, or disconnecting the active metadata server and
     ensuring that it is restarted before accessing the file
     system again.  Doing so will cause file system corruption.

SEE ALSO
     sammkfs(1M).