C H A P T E R 4

Configuring a Sun StorEdge QFS Shared File System

This chapter describes how to configure and maintain a Sun StorEdge QFS shared file system. This chapter contains the following sections:

- Mounting and Unmounting Sun StorEdge QFS Shared File Systems

- Converting an Unshared File System to a Shared File System

- Converting a Shared File System to an Unshared File System

- Adding and Removing a Client Host

- Changing the Metadata Server in a Sun StorEdge QFS Environment

- Client-Server Communications in a Sun StorEdge QFS Shared File System

##

Mounting and Unmounting Sun StorEdge QFS Shared File Systems

When you mount or unmount a Sun StorEdge QFS shared file system, the order in which you mount or unmount the metadata server and the clients is important.

For failover purposes, the mount options should be the same on the metadata server and all potential metadata servers. For example, you can create a `samfs.cmd`(4) file containing mount options and copy it to all of the hosts.

For more information about mounting Sun StorEdge QFS shared file systems, see Mount Options in a Sun StorEdge QFS Shared File System and see the `mount_samfs`(1M) man page. For more information about mounting and unmounting file systems, see Chapter 3, Performing Operational Tasks.

### To Mount a Shared File System

1. Become superuser on the metadata server and on all the client hosts.

2. Use the `mount`(1M) command to mount the metadata server.

Mount the file system on the metadata server before mounting it on any client hosts.

3. Use the `mount`(1M) command to mount the client hosts.

You can mount the file system on the client hosts in any order.

For more information about the `mount`(1M) command, see the `mount`(1M) man page.

### To Unmount a Shared File System

1. Use the `umount`(1M) command to unmount the file system on every participating client host.

For example:

    # umount /samqfs

If necessary, use the `-f` option to the `umount`(1M) command. The `-f` option forces a file system to unmount.

2. Unmount the file system on the metadata server:

    # umount /samqfs

Several conditions can be present in a file system at unmounting time, so you might need to issue the `umount`(1M) command a second time. If the file system still does not unmount, use `unshare`(1M), `fuser`(1M), or another command in conjunction with the `umount`(1M) command. For more information on unmounting procedures, see the `umount`(1M) man page and the Sun StorEdge QFS Installation and Upgrade Guide.

##

Converting an Unshared File System to a Shared File System

To perform initial installation and configuration for a Sun StorEdge QFS shared file system, follow the instructions in the Sun StorEdge QFS Installation and Upgrade Guide. Many examples in this chapter use host names and configuration information that were introduced in that guide.

To convert an unshared Sun StorEdge QFS file system to a Sun StorEdge QFS shared file system, you must perform the conversion first on the metadata server and then on each client. This section describes these procedures.

### To Perform a Conversion

You must have `root` permission to complete the steps in this procedure.

1. As superuser, log in to the system to be used as the primary metadata server.

2. Back up all site-customized system files and configuration files.

Depending on your software, these files might include `mcf`(4), `archiver.cmd`, `defaults.conf`, `samfs.cmd`, `inquiry.conf`, and so on. Back up these files for all file systems. Also make sure that you have backup copies of files in the `/etc/opt/SUNWsamfs` directory, and files in the `/var/opt/SUNWsamfs` directory.

3. Ensure that each file system to be modified is backed up.

File systems should be backed up regularly according to your site's policies. If you are comfortable with the backup files that already exist for your file systems, there is no need to back them up again now.

4. Use the `umount`(1M) command to unmount the file system.

For instructions, see Unmounting a File System.

5. Use the `samfsck`(1M) `-S -F` family-set-name command to convert the file system to a Sun StorEdge QFS shared file system.

For family-set-name, specify the family set name of the file system that you are converting to a new Sun StorEdge QFS shared file system. For example:

    # samfsck -S -F sharefs1

6. Edit the `/etc/opt/SUNWsamfs/mcf` file to add the `shared` keyword in the file system's Additional Parameters field.

For example:

CODE EXAMPLE 4-1 `mcf` File for Shared File System, `sharefs1`
    # Equipment                      Eq  Eq   Family   Dev   Add
    # Identifier                     Ord Type Set      State Params
    # ----------                     --- ---- ------   ----- ------
    sharefs1                         10  ma   sharefs1 on    shared
    /dev/dsk/c2t50020F23000065EEd0s6 11  mm   sharefs1 on
    /dev/dsk/c7t50020F2300005D22d0s6 12  mr   sharefs1 on
    /dev/dsk/c7t50020F2300006099d0s6 13  mr   sharefs1 on
    /dev/dsk/c7t50020F230000651Cd0s6 14  mr   sharefs1 on

7. Edit the `/etc/vfstab` file to add the `shared` keyword in the file system's Mount Parameters field.

For example:

CODE EXAMPLE 4-2 `/etc/vfstab` File Example
    # File /etc/vfstab
    # FS name   FS to fsck    Mnt pt    FS type   fsck pass   Mt@boot   Mt params
    sharefs1    -             /sharefs1 samfs     -            no         shared

8. Create the `/etc/opt/SUNWsamfs/hosts.`fsname hosts configuration file.

For example:

CODE EXAMPLE 4-3 Sun StorEdge QFS Shared File System Hosts File Example
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan 	titan-ge0 	1        - 	server
    tethys 	tethys-ge0	2        - 	server

See the Sun StorEdge QFS Installation and Upgrade Guide for more information about creating the hosts configuration file.

9. Run the `samsharefs`(1M) `-u -R` family-set-name command to initialize the file system and the host configuration.

For example:

    # samsharefs -u -R sharefs1

Note - This command might issue an error message, which can be ignored.

10. Run the `samd`(1M) `config` command:

    # samd config

This informs the `sam-fsd` daemon of the configuration changes.

11. Issue the `mount`(1M) command to mount the file system.

### To Perform a Conversion on Each Client

1. Use the `mkdir`(1) command to create the mount point for the file system.

For example:

    # mkdir /sharefs1

2. (Optional) Create an `/etc/opt/SUNWsamfs/hosts.`file-system-name`.local` local hosts configuration file.

You might want to perform this step if your Sun StorEdge QFS shared host systems have multiple host interfaces. The local hosts configuration file defines the host interfaces that the metadata server and the client hosts can use when accessing the file system. You use this file to specify how file system traffic should flow over public and private networks in your environment.

CODE EXAMPLE 4-4 shows a sample local hosts configuration file.

CODE EXAMPLE 4-4 File `hosts.sharefs1.local`
    # This is file /etc/opt/SUNWsamfs/hosts.sharefs1.local
    # Host Name    Host Interfaces
    # ---------    ---------------
    titan          172.16.0.129
    tethys         172.16.0.130

For more information on creating the local hosts file, see Creating the Local Hosts Configuration File.

3. If you want to move files from an existing Sun StorEdge QFS file system into a new Sun StorEdge QFS shared file system, ensure that each file system to be modified is backed up.

File systems should be backed up regularly according to your site's policies. If you are comfortable with the backup files that already exist for your file systems, there is no need to back them up again now.

4. Use the `umount`(1M) command to unmount the file system.

For instructions, see Unmounting a File System.

5. Edit the `/etc/vfstab` file to add the `shared` keyword in the file system's Mount Parameters field.

For example:

    # File /etc/vfstab
    # FS name   FS to fsck    Mnt pt    FS type   fsck pass   Mt@boot   Mt params
    sharefs1    -             /sharefs1 samfs     -            no         shared

6. Create the `/etc/opt/SUNWsamfs/hosts.`fsname hosts configuration file.

CODE EXAMPLE 4-5 shows a sample.

CODE EXAMPLE 4-5 Sun StorEdge QFS Shared File System Hosts File Example
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan 	titan-ge0 	1        - 	server
    tethys 	tethys-ge0	2        - 	server

For more information about creating the hosts configuration file, see the Sun StorEdge QFS Installation and Upgrade Guide.

##

Converting a Shared File System to an Unshared File System

To convert a Sun StorEdge QFS shared file system to an unshared Sun StorEdge QFS file system, you must perform the conversion first on each client and then on the metadata server. This section describes these procedures.

### To Perform a Conversion on Each Client

1. Use the `umount`(1M) command to unmount the file system.

For instructions, see Unmounting a File System.

2. Delete the file system's entry from the `/etc/opt/SUNWsamfs/mcf` file.

3. Delete the file system's entry from the `/etc/vfstab` file.

4. Run the `samd`(1M) `config` command:

    # samd config

This informs the `sam-fsd` daemon of the configuration changes.

5. Delete the mount point for the file system.

### To Perform a Conversion on the Server

You must have `root` permission to complete the steps in this procedure.

1. As superuser, log in to the metadata server system.

2. Back up all site-customized system files and configuration files.

Depending on your software, these files might include `mcf`(4), `archiver.cmd`, `defaults.conf`, `samfs.cmd`,`inquiry.conf`, and so on. Back up these files for all file systems. Also make sure that you have backup copies of files in the `/etc/opt/SUNWsamfs` directory and files in the `/var/opt/SUNWsamfs` directory.

3. If you want to move files from an existing Sun StorEdge QFS shared file system into a new Sun StorEdge QFS file system, ensure that each file system to be modified is backed up.

File systems should be backed up regularly according to your site's policies. This is described as the last step in the installation procedure. If you are comfortable with the backup files that already exist for your file systems, there is no need to back them up again now.

4. Use the `umount`(1M) command to unmount the file system.

For instructions, see Unmounting a File System.

5. Run the `samfsck`(1M)`-F -U` file-system-name to convert the Sun StorEdge QFS shared file system to an unshared file system.

For file-system-name, specify the name of the Sun StorEdge QFS shared file system that you are converting to a new unshared file system. For example:

    # samfsck -F -U samfs1

6. Edit the `/etc/opt/SUNWsamfs/mcf` file to remove the `shared` keyword from the file system's Additional Parameters field.

For example:

    # Equipment                      Eq  Eq   Family   Dev   Add
    # Identifier                     Ord Type Set      State Params
    # ----------                     --- ---- ------   ----- ------
    samfs1                           10  ma   samfs1   on
    /dev/dsk/c2t50020F23000065EEd0s6 11  mm   samfs1   on
    /dev/dsk/c7t50020F2300005D22d0s6 12  mr   samfs1   on
    /dev/dsk/c7t50020F2300006099d0s6 13  mr   samfs1   on
    /dev/dsk/c7t50020F230000651Cd0s6 14  mr   samfs1   on

7. Edit the `/etc/vfstab` file to remove the `shared` keyword from the file system's Mount Parameters field.

For example:

    # File /etc/vfstab
    # FS name   FS to fsck    Mnt pt    FS type   fsck pass   Mt@boot   Mt params
    samfs1    -             /samfs1      samfs     -            no

8. Delete the `/etc/opt/SUNWsamfs/hosts.`file-system-name configuration file.

9. Run the `samd`(1M) `config` command:

    # samd config

This informs the `sam-fsd` daemon of the configuration changes.

10. Issue the `mount`(1M) command to mount the file system.

##

Adding and Removing a Client Host

The following subsections provide instructions for adding and removing client host systems in a Sun StorEdge QFS shared file system:

- To Add a Client Host

- To Remove a Client Host

- Updating the mcf file in a Sun StorEdge QFS Shared Environment

- Creating the Local Hosts Configuration File

### To Add a Client Host

You can add a client host to a Sun StorEdge QFS shared file system after you have configured and mounted the file system on all participants. If you are adding a client host that is a node in a Sun Cluster environment, you must add the node to the cluster's existing resource group. For more information, see the Sun Cluster System Administration Guide for Solaris OS.

1. Become superuser on the metadata server.

2. Use the `samsharefs`(1M) command to retrieve the current Sun StorEdge QFS shared file system information and write it to an editable file.

- If the Sun StorEdge QFS shared file system is mounted, issue the `samsharefs`(1M) command on the current metadata server. For example:

    # samsharefs sharefs1 > /etc/opt/SUNWsamfs/hosts.sharefs1

- If the Sun StorEdge QFS shared file system is unmounted, issue the `samsharefs`(1M) command with its `-R` option from the metadata server or from any of the potential metadata servers. For example:

    # samsharefs -R sharefs1 > /etc/opt/SUNWsamfs/hosts.sharefs1

You can issue the `samsharefs`(1M) command only on the active metadata server or on client hosts configured as potential metadata servers. For more information, see the `samsharefs`(1M) man page.

3. Use `vi`(1) or another editor to open the Sun StorEdge QFS shared file system information file.

CODE EXAMPLE 4-6 shows this step.

CODE EXAMPLE 4-6 `hosts.sharefs1` Before Editing
    # vi /etc/opt/SUNWsamfs/hosts.sharefs1
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan    172.16.0.129 	1        -    server
    tethys   172.16.0.130 	2        -
    mimas    mimas 	-        -
    dione    dione 	-        -

4. Use the editor to add a line for the new client host.

CODE EXAMPLE 4-7 shows the file after addition of the line for `helene` as the last line.

CODE EXAMPLE 4-7 `hosts.sharefs1` After Editing
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan    172.16.0.129 	1        -    server
    tethys   172.16.0.130 	2        -
    mimas    mimas - 	-
    dione    dione - 	-
    helene   helene - 	-

5. Use the `samsharefs`(1M) command to update the current information in the binary file.

The options to use with this command, and the system from which this command is issued, depend on whether the Sun StorEdge QFS shared file system is mounted, as follows:

- If the file system is mounted, issue the `samsharefs`(1M) `-u` command from the current metadata server. For example:

    # samsharefs -u sharefs1

- If the file system is unmounted, issue the `samsharefs`(1M) `-R` `-u` command from the active metadata server or from any of the potential metadata servers. For example:

    # samsharefs -R -u sharefs1

The client host `helene` is now recognized.

6. As superuser, log in to the client host to be added.

7. Use the `format`(1M) command to verify the presence of client host disks.

8. Update the `mcf`(4) file on the client host.

Before a host system can access or mount a shared file system, it must have that file system defined in its `mcf`(4) file. The `mcf`(4) file must be updated to match all client hosts in the Sun StorEdge QFS shared file system. The file system and disk declaration information must have the same data for the Family Set Name, Equipment Ordinal, and Equipment Type as the configuration on the metadata server. The `mcf`(4) files on the client hosts must also include the shared keyword. The device names, however, can change, since controller assignments will probably differ from host to host.

For information on how to edit the `mcf`(4) file, see Updating the mcf file in a Sun StorEdge QFS Shared Environment .

9. Issue the `samd`(1M) `config` command on the metadata server host:

    # samd config

This informs the `sam-fsd` daemon of the configuration changes.

10. (Optional) Create the local hosts configuration file on the new client host.

You might want to perform this step if your Sun StorEdge QFS shared host systems have multiple host interfaces. The local hosts configuration file defines the host interfaces that the metadata server and the client hosts can use when accessing the file system. You use this file to specify how file system traffic should flow over public and private networks in your environment.

For information on creating the local hosts file, see Creating the Local Hosts Configuration File.

11. Issue the `samd`(1M) `config` command on the client host:

    # samd config

This informs the `sam-fsd` daemon of the configuration changes.

12. Verify that the `sam-sharefsd` daemon is running for this file system.

To accomplish this, use the `ps`(1) and `grep`(1) commands as shown in CODE EXAMPLE 4-8.

CODE EXAMPLE 4-8 Output from the `ps` (1) Command
    # ps -ef | grep sam-sharefsd
    root 26167 26158  0 18:35:20 ?        0:00 sam-sharefsd sharefs1
    root 27808 27018  0 10:48:46 pts/21   0:00 grep sam-sharefsd

CODE EXAMPLE 4-8 shows that the `sam-sharefsd` daemon is active for the `sharefs1` file system. If the output returned on your system does not show that the `sam-sharefsd` daemon is active for your Sun StorEdge QFS shared file system, perform the diagnostic procedures described in Troubleshooting a Failed or Hung sammkfs(1M) or mount(1M) Command in a Shared File System.

13. If the new Sun StorEdge QFS shared file system does not already have a mount point, use the `mkdir`(1) command to make the directory for the mount point.

For example:

    # mkdir /sharefs1

14. Issue the `chmod`(1M) command to give the mount point the `755` set of permissions.

For example:

    # chmod 755 /sharefs1

The permissions must be the same on all participant hosts. `755` is suggested as the initial permission set because users must have execute permission on the mount point in order to be able to use the file system after it has been mounted. After you mount the file systems, the `root` directory's permissions override this setting.

15. Modify the `/etc/vfstab` file.

You must have an entry in the `/etc/vfstab` file for the Sun StorEdge QFS shared file system. Specify `shared` in the Mount Parameters field. In addition, do one of the following:

- If you do not want to mount this file system automatically at boot time, type `no` in the `Mt@boot` field.

- If you do want the Sun StorEdge QFS shared file system to automatically mount at boot, do the following:

- Type yes in the `Mt@boot` field.

- Add the `bg` mount option in the `Mt params` field. The `bg` mount option mounts the file system in the background if the metadata server is not responding.

CODE EXAMPLE 4-9 shows the `shared` and `bg` entries in the `Mt params` field.

CODE EXAMPLE 4-9 `/etc/vfstab` File Example
    # File /etc/vfstab
    # FS name  FS to fsck  Mnt pt   FS type  fsck  Mt@boot  Mt params
    #                                        pass
    sharefs1   -           /sharefs1 samfs   -     yes      shared,bg

16. Issue the `df`(1M) command on the metadata server to verify that the file system is mounted on the metadata server.

For example:

    # df -k

The file system should be included in the displayed list.

17. From the client host, issue the `mount`(1M) command to mount the Sun StorEdge QFS shared file system.

For example:

    # mount /sharefs1

For more information about mounting Sun StorEdge QFS shared file systems, see Mount Options in a Sun StorEdge QFS Shared File System, or see the `mount_samfs`(1M) man page.

### To Remove a Client Host

1. Become superuser on the metadata server and on all the client hosts.

Note - You can use the `samsharefs`(1M) command to verify that you are, indeed, logged in to the metadata server or a client host.

2. Use the `umount`(1M) command to unmount the Sun StorEdge QFS shared file system on each client host on which the Sun StorEdge QFS shared file system is mounted.

For example:

    client# umount sharefs1

3. Use the `umount`(1M) command to unmount the Sun StorEdge QFS shared file system on the metadata server.

For example:

    metaserver# umount sharefs1

4. If you have not already done so, log in as superuser to the metadata server for the Sun StorEdge QFS shared file system.

5. Use the `samsharefs`(1M) command to obtain the current configuration information.

The following example command writes current configuration information to file `/etc/opt/SUNWsamfs/hosts.sharefs1`:

    # samsharefs -R sharefs1 > /etc/opt/SUNWsamfs/hosts.sharefs1

6. Use `vi`(1) or another editor to open the Sun StorEdge QFS shared file system information file.

CODE EXAMPLE 4-10 shows the file before the client host is deleted.

CODE EXAMPLE 4-10 `hosts.sharefs1` Before Deleting a Client Host
    # vi /etc/opt/SUNWsamfs/hosts.sharefs1
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan    172.16.0.129 	1        -    server
    tethys   172.16.0.130 	2        -
    mimas    mimas - 	-
    dione    dione - 	-
    helene   helene -	-

7. Use the editor to delete the client host or hosts that are no longer to be supported.

CODE EXAMPLE 4-11 shows the file after the line for `helene` has been deleted.

CODE EXAMPLE 4-11 `hosts.sharefs1` After Deleting a Client Host
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan    172.16.0.129 	1        -    server
    tethys   172.16.0.130 	2        -
    mimas    mimas - 	-
    dione    dione - 	-

8. Use the `samsharefs`(1M) `-R -u` command to update the current hosts information.

For example:

    # samsharefs -R -u sharefs1

The host `helene` has been removed.

9. Use the `samsharefs`(1M) `-R` command to display the current configuration.

For example:

    # samsharefs -R sharefs1

10. Use the `mount`(1M) command to mount the Sun StorEdge QFS shared file system, first on the metadata server and then on each client host in the file system.

For information about the `mount`(1M) command, see the `mount_samfs`(1M) man page.

### Updating the `mcf` file in a Sun StorEdge QFS Shared Environment

The `samfsconfig`(1M) command generates configuration information that can help you to identify the devices included in the Sun StorEdge QFS shared file system. You can then use this information to update the `mcf`(4) files on each client host.

Enter a separate `samfsconfig`(1M) command on each client host. Note that the controller number might not be the same controller number as on the metadata server because the controller numbers are assigned by each client host.

Note - If you update a metadata server's `mcf`(4) file after the Sun StorEdge QFS shared file system is mounted, be sure to update the `mcf`(4) files on all hosts that can access that shared file system.

Example 1. CODE EXAMPLE 4-12 shows how the `samfsconfig`(1M) command is used to retrieve device information for family set `sharefs1` on client `tethys`. Because `tethys` is a potential metadata server, it is connected to the same metadata disks as `titan`, another metadata server in the shared file system.

CODE EXAMPLE 4-12 `samfsconfig` (1M) Command Example on `tethys`
    tethys# samfsconfig /dev/dsk/*
    #
    # Family Set 'sharefs1' Created Wed Jun 27 19:33:50 2003
    #
    sharefs1                         10 ma sharefs1 on shared
    /dev/dsk/c2t50020F23000065EEd0s6 11 mm sharefs1 on
    /dev/dsk/c7t50020F2300005D22d0s6 12 mr sharefs1 on
    /dev/dsk/c7t50020F2300006099d0s6 13 mr sharefs1 on
    /dev/dsk/c7t50020F230000651Cd0s6 14 mr sharefs1 on

Edit the `mcf`(4) file on client host `tethys` by copying the last five lines of output from the `samfsconfig`(1M) command into the `mcf`(4) file on client host `tethys`. Verify the following:

- Each Device State field is set to `on`.

- The `shared` keyword appears in the Additional Parameters field for the file system name.

CODE EXAMPLE 4-13 shows the resulting `mcf`(4) file.

CODE EXAMPLE 4-13 `mcf` File for `sharefs1` Client Host `tethys`
    # Equipment                      Eq  Eq   Family   Dev   Add
    # Identifier                     Ord Type Set      State Params
    # ----------                     --- ---- ------   ----- ------
    sharefs1                         10  ma   sharefs1 on    shared
    /dev/dsk/c2t50020F23000065EEd0s6 11  mm   sharefs1 on
    /dev/dsk/c7t50020F2300005D22d0s6 12  mr   sharefs1 on
    /dev/dsk/c7t50020F2300006099d0s6 13  mr   sharefs1 on
    /dev/dsk/c7t50020F230000651Cd0s6 14  mr   sharefs1 on

Example 2. CODE EXAMPLE 4-14 shows how the `samfsconfig`(1M) command is used to retrieve device information for family set `sharefs1` on client host `mimas`. In this example, `mimas` can never become a metadata server, and it is not connected to the metadata disks.

CODE EXAMPLE 4-14 `samfsconfig` (1M) Command Example on `mimas`
    mimas# samfsconfig /dev/dsk/*
    #
    # Family Set 'sharefs1' Created Wed Jun 27 19:33:50 2001
    #
    # Missing slices
    # Ordinal 0
    # /dev/dsk/c1t50020F2300005D22d0s6   12    mr   sharefs1   on
    # /dev/dsk/c1t50020F2300006099d0s6   13    mr   sharefs1   on
    # /dev/dsk/c1t50020F230000651Cd0s6   14    mr   sharefs1   on

In the output from the `samfsconfig`(1M) command on `mimas`, note that `Ordinal` 0, which is the metadata disk, is not present. For devices that are missing, the `samfsconfig`(1M) process comments out the elements of the file system and omits the file system Family Set declaration line. Make the following types of edits to the `mcf`(4) file:

- Create a file system Family Set declaration line, beginning with `sharefs1`, in the `mcf`(4) file for client host `mimas`. Enter the `shared` keyword in the Additional Parameters field of the file system Family Set declaration line.

- Create one or more `nodev` lines for each missing Equipment Ordinal entry. For each of these lines, the keyword `nodev` must appear in the Equipment Identifier field for the inaccessible device.

- Ensure that each Device State field is set to `on`.

- Uncomment the device lines.

CODE EXAMPLE 4-15 shows the resulting `mcf`(4) file for `mimas`.

CODE EXAMPLE 4-15 `mcf` File for Client Host `mimas`
    # The mcf File For mimas
    # Equipment                      Eq  Eq   Family   Device Addl
    # Identifier                     Ord Type Set      State  Params
    ------------                     --- ---- ---      -----  ------
    sharefs1                         10  ma   sharefs1 on     shared
    nodev                            11  mm   sharefs1 on
    /dev/dsk/c1t50020F2300005D22d0s6 12  mr   sharefs1 on
    /dev/dsk/c1t50020F2300006099d0s6 13  mr   sharefs1 on
    /dev/dsk/c1t50020F230000651Cd0s6 14  mr   sharefs1 on

### Creating the Local Hosts Configuration File

The local hosts configuration file must reside in the following location:

    /etc/opt/SUNWsamfs/hosts.family-set-name.local

Comments are permitted in the local hosts configuration file. Comment lines must begin with a pound character (`#`). Characters to the right of the pound character are ignored.

TABLE 4-1 shows the fields in the local hosts configuration file.

TABLE 4-1 Local Hosts Configuration File Fields
Field | Content
--- | ---
Host Name | This field must contain the alphanumeric name of a metadata server or potential metadata server that is part of the Sun StorEdge QFS shared file system.
Host Interfaces | This field must contain a comma-separated list of host interface addresses. This field can be created from the output received from the `ifconfig`(1M) `-a` command. The individual interfaces can be specified in one of the following ways: Dotted-decimal IP address form IP version 6 hexadecimal address form As a symbolic name that the local domain name service (DNS) can resolve to a particular host interface Each host uses this field to determine whether it will try to connect to the specified host interface. The system evaluates the addresses from left to right, and the connection is made using the first responding address in the list that is also included in the shared hosts file.

In a Sun StorEdge QFS shared file system, each client host obtains the list of metadata server IP addresses from the metadata server host.

The metadata server and the client hosts use both the `/etc/opt/SUNWsamfs`/`hosts.`fsname file on the metadata server and the `hosts.`fsname`.local` file on each client host (if it exists) to determine the host interface to use when accessing the file system. This process is as follows (note that client, as in network client, is used to refer to both client hosts and the metadata server host):

1. The client obtains the list of metadata server host IP interfaces from the file system's on-disk host file.

To examine this file, issue the `samsharefs`(1M) command from the metadata server or from a potential metadata server.

2. The client searches its files for a `hosts.`fsname`.local` file.

Depending on the outcome of the search, one of the following courses of action is taken:

- If a `hosts.`fsname`.local` file does not exist, the client attempts to connect, in turn, to each address in the system hosts configuration file until it succeeds.

- If the `hosts.`fsname`.local` file exists, the client performs the following tasks:

a. It compares the list of addresses for the metadata server from both the `/etc/opt/SUNWsamfs`/`hosts.`fsname file on the metadata server and the `hosts.`fsname`.local` file.

b. It builds a list of addresses that are present in both places, and then it attempts to connect to each of these addresses, in turn, until it succeeds. If the order of the addresses differs in these files, the client uses the ordering in the `hosts.`fsname`.local` file.

Example. CODE EXAMPLE 4-16 shows an example hosts file listing four hosts.

CODE EXAMPLE 4-16 Sun StorEdge QFS Shared File System Hosts File Example
    # File /etc/opt/SUNWsamfs/hosts.sharefs1
    # Host   Host IP                           Server   Not  Server
    # Name   Addresses                         Priority Used Host
    # ----   --------------------------------- -------- ---- -----
    titan    172.16.0.129 	1        -    server
    tethys   172.16.0.130 	2        -
    mimas    mimas - 	-
    dione    dione - 	-

FIGURE 4-1 shows the interfaces to these systems.

FIGURE 4-1 Network Interfaces

[ D ]

Systems `titan` and `tethys` share a private network connection with interfaces `172.16.0.129` and `172.16.0.130`. To guarantee that `titan` and `tethys` always communicate over their private network connection, the system administrator has created identical copies of `/etc/opt/SUNWsamfs/hosts.sharefs1.local` on each system. CODE EXAMPLE 4-17 shows the information in these files.

CODE EXAMPLE 4-17 File `hosts.sharefs1.local` on `titan` and `tethys`
    # This is file /etc/opt/SUNWsamfs/hosts.sharefs1.local
    # Host Name    Host Interfaces
    # ---------    ---------------
    titan          172.16.0.129
    tethys         172.16.0.130

Systems `mimas` and `dione` are not on the private network. To guarantee that they always connect to `titan` and `tethys` through `titan`'s and `tethys`'s public interfaces, the system administrator has created identical copies of `/etc/opt/SUNWsamfs/hosts.sharefs1.local` on `mimas` and `dione`. CODE EXAMPLE 4-18 shows the information in these files.

CODE EXAMPLE 4-18 File `hosts.sharefs1.local` on `mimas` and `dione`
    # This is file /etc/opt/SUNWsamfs/hosts.sharefs1.local
    # Host Name    Host Interfaces
    # ----------   --------------
    titan          titan
    tethys         tethys

##

Changing the Metadata Server in a Sun StorEdge QFS Environment

The procedures in this section describe how to change the host that is acting as the metadata server in a Sun StorEdge QFS shared file system without using the automatic Membership Services feature of a software package such as Sun Cluster software.

You can change the metadata server system manually under the following circumstances:

- If the metadata server becomes unavailable

- If you want to change the metadata server or the potential metadata servers

For a metadata server change to succeed, the mount options of the existing metadata server and all potential metadata servers must be the same.

Choose one of the following procedures depending on whether the existing metadata server is available at the time the change is being performed:

- To Change the Metadata Server When the Metadata Server Is Available

- To Change the Metadata Server When the Metadata Server Is Unavailable

### To Change the Metadata Server When the Metadata Server Is Available

On the existing metadata server, issue the `samsharefs`(1M) `-s` command to declare the new metadata server.

For example:

    titan# samsharefs -s tethys sharefs1

### To Change the Metadata Server When the Metadata Server Is Unavailable

If the metadata server of a shared file system crashes, it is safe to change the metadata server only after rebooting the metadata server or otherwise ensuring that the server cannot issue any I/O before being rebooted. Do not use any of the following methods to stop the server, because these are likely to corrupt the file system:

- Issuing an L1-A key sequence

- Performing an involuntary failover to another host

- Issuing a `go` (continue) command, requesting a dump file, or issuing a `sync` command to the old metadata server.

Similarly, if the metadata server panics and drops into kernel `adb`(1), do not change the metadata server and then issue `:c` (continue) command on the server. This action causes the old metadata server to push stale buffers out to the now active file system.

Use the following steps to change the metadata server:

1. Ensure that the existing metadata server cannot restart without being rebooted.

Specifically, ensure that the server is powered down, rebooted, halted, or disconnected from the metadata disks. Your goal is to bring down the old metadata server and flush or destroy all buffers (or otherwise ensure that they cannot be rewritten).

CODE EXAMPLE 4-19 shows the key sequence to use from the `kadb` prompt.

CODE EXAMPLE 4-19 Key Sequence for Ensuring that the Metadata Server Cannot Restart from the `kadb` Prompt
    kadb[1]: sync 	# Forces a dump
    kadb[1]: $q 	# Exits the debugger for prom

CODE EXAMPLE 4-20 shows the key sequence to use from the PROM prompt.

CODE EXAMPLE 4-20 Key Sequence for Ensuring that the Metadata Server Cannot Restart from the PROM Prompt
    {0} > sync         # Forces the buffers out
    {0} > boot args     # Discards buffers

For args, specify arguments for the `boot`(1M) command, such as `-r` or `-v`. For more information, see the `boot`(1M) man page.

2. From the new (potential) metadata server, wait for at least the period of the maximum lease time, and then issue the `samsharefs`(1M) command.

For example:

    # samsharefs -R -s tethys sharefs1

The wait ensures that all client leases expire before you issue the `samsharefs`(1M) command. If you are uncertain as to whether the lease time has expired, bring up the `samu`(1M) `N` display. For information about `samu`(1M), see Using the samu(1M) Operator Utility. For information about leases and their durations, see Using Leases in a Sun StorEdge QFS Shared File System: the rdlease=n, wrlease=n, and aplease=n Options.

| Caution - If you use the `-R`option to the `samsharefs`(1M) command on a mounted file system to change the metadata server host, you must first stop, disable, and disconnect the active metadata server. Failure to do so can cause file system corruption.

3. (Optional) Unmount the file system.

Perform this step only if you want to perform a file system check.

Use the procedure in To Unmount a Sun StorEdge QFS Shared File System.

4. (Optional) Issue the `samfsck`(1M) command to perform a file system check.

If the metadata server of a Sun StorEdge QFS shared file system crashes, the server should be rebooted and the file system should be unmounted on all clients before `samfsck`(1M) is run. The server and clients preallocate blocks before changing the length of files. The `samfsck`(1M) command cleans up files that have extra blocks allocated, and these extra blocks might contain data. If such a cleaned-up file is awaiting a size update from the client, the file will be missing those blocks when the client continues. As a result, the file will be missing data, and the missed data will read as zeroes.

##

Changing the Metadata Server in a SAM-QFS Environment

The procedures in this section describe how to change the host that is acting as the metadata server in a SAM-QFS shared file system without using the automatic Membership Services feature of a software package such as Sun Cluster software.

You can change the metadata server system manually under the following circumstances:

- If the metadata server becomes unavailable

- If you want to change the metadata server or the potential metadata servers

For a metadata server change to succeed, the mount options of the existing metadata server and all potential metadata servers must be the same.

### To Change the Metadata Server in a SAM-QFS Environment

Sun StorEdge SAM-FS can only be running on one host at any time. This procedure assumes that both system are up at the time of the transfer. In this example we are moving Sun StorEdge SAM-FS archiving functions from host A to host B.

Before carrying out this procedure, verify that host B has access to the robot catalog from host A. The `archiver.cmd` file, `mcf` file, `stager.cmd` file, and other configuration files must be identical to those on host A.

1. Idle Sun StorEdge SAM-FS archiving processes on host A by carrying out the following steps:

a. Run `samcmd aridle` and `samcmd stidle` to halt archiving and staging on host A.

These commands will allow current archiving and staging to complete, but will not start any new work.

b. Idle all of the tape drives on host A.

This can be done with `samcmd` eq `idle`, where eq is the equipment ordinal of the drive. This will put the drives in an "off" state after any current IO completes.

c. When the archiver and stager are idle and the tape drives are all in the "off" state, run the `samd stop` command to halt all of the robot and tape-related daemons.

d. If you have a cron job that runs the recycler, remove this entry from the crontab and verify that the recycler is not currently running.

At this point, Sun StorEdge SAM-FS has been halted and filesystem failover to host B can be performed.

2. Start Sun StorEdge SAM-FS on host B by running `samd config` on host B.

This causes `sam-fsd` and its sub-processes (archiver, stager, and so on) to reconfigure and re-read the configuration files. It also causes `sam-amld` and the tape-library-related daemons to start. At this point all Sun StorEdge QFS shared client applications waiting for stages must reissue the stage requests.

Host B should now be fully functioning as the Sun StorEdge SAM-FS server and metadata server for all Sun StorEdge QFS file systems.

##

Client-Server Communications in a Sun StorEdge QFS Shared File System

The behavior of the Sun StorEdge QFS shared file system is that of an interruptible hard connection. Each client tries repeatedly to communicate with the metadata server, even if the server is unavailable. If the metadata server is not responding, a user can terminate any pending, blocked I/O transmission by pressing Ctrl-C. If the I/O attempt is interrupted, the client persists until the I/O completes.

The system generates the following messages to describe status conditions:

    SAM-FS: Shared server is not responding.

This message is also generated if the client `sam-sharefsd` daemon is not active or if the server `sam-sharefsd` daemon is not active. When the server responds, it generates the following message:

    SAM-FS: Shared server is responding.

If the file system is not mounted on the metadata server, but it is mounted on the client, the system generates the following message:

    SAM-FS: Shared server is not mounted.

When the Sun StorEdge QFS shared file system mounts on the server, it generates the following message:

    SAM-FS: Shared server is mounted.

Because the metadata server looks up file names on behalf of all clients, performance can be slow with the default size of the Solaris directory name lookup cache (DNLC) on the metadata server. To increase performance when clients are frequently opening a large number of files, you might want to double or even triple the size of this cache from its default.

This procedure is documented in the Solaris Tunable Parameters Reference Manual. The parameter that controls the size of the directory name lookup cache is `ncsize`.

Copyright © 2006, Sun Microsystems, Inc. All Rights Reserved.