C H A P T E R 3

Sun StorEdge QFS Upgrade Procedure

This chapter describes upgrading a server to a new release of the Sun StorEdge software. Use this procedure if you are upgrading your Sun StorEdge QFS file system. You must perform all the tasks in this chapter as superuser.

The main tasks, which must be completed in order, are as follows:

- Ensuring That the Installation Prerequisites Are Met

- (Optional) Backing Up Existing File Systems

- (Optional) Unsharing the File Systems1

- Unmounting the File Systems

- Removing Existing Sun StorEdge QFS Software

- Adding the Packages

- Updating the License Keys

- (Optional) Enabling the SAM-QFS Manager

- Verifying the License and mcf Files

- (Optional) Modifying the /etc/vfstab File

- (Optional) Reinitializing and Restoring the File Systems

- (Optional) Checking the File System

- Mounting the File Systems

- (Optional) Recompiling API-Dependent Applications

##

Ensuring That the Installation Prerequisites Are Met

System Requirements and Preinstallation Tasks describes the items you need to verify before you upgrade to the Sun StorEdge QFS 4.1 release. If you have not yet completed the system verification steps, complete them now before you proceed. The steps described in that chapter that pertain to verifying the system requirements for your upgrade to release 4.2 are as follows:

- Server Requirements

- Solaris Operating System Requirements

- Verifying Disk Space

- Obtaining a Software License Key

- Obtaining the Release Files

- Verifying Third-Party Compatibilities

- (Optional) Verifying Requirements for the SAM-QFS Manager

- (Optional) Verifying the Network Management Station

##

(Optional) Backing Up Existing File Systems

Perform this task if the following conditions exist:

- You are currently using a version 1 superblock with a Sun QFS 4.0 system and you want to reinitialize your file systems with a version 2 superblock. In (Optional) Reinitializing and Restoring the File Systems, you reinitialize the file systems and restore your data.

- You suspect that your current `qfsdump`(1M) file is incorrect or outdated.

The following sections explain the differences between these two superblocks and present the procedure for backing up your file systems:

- Using the Version 1 and Version 2 Superblocks

- To Back Up Each File System

CODE EXAMPLE 3-1 shows using the `samfsinfo`(1M) command to retrieve information about the `qfs2` file system. The second line of output indicates that this file system is using a version 2 superblock.

CODE EXAMPLE 3-1 Using `samfsinfo` (1M)
    # samfsinfo qfs2
    samfsinfo: filesystem qfs2 is mounted.
    name: qfs2       version:     2    shared
    time:     Sun Sep 28 08:20:11 2003
    count:    3
    capacity:      05aa8000          DAU:         64
    space:         0405ba00
    meta capacity: 00b4bd20          meta DAU:    16
    meta space:    00b054c0
    ord  eq   capacity      space   device
      0  21   00b4bd20   00b054c0   /dev/md/dsk/d0
      1  22   02d54000   01f43d80   /dev/dsk/c9t50020F2300010D6Cd0s6
      2  23   02d54000   02117c80   /dev/dsk/c9t50020F2300010570d0s6

### Using the Version 1 and Version 2 Superblocks

The Sun StorEdge QFS 4.0, 4.1, and 4.2 releases support both a version 1 superblock and a version 2 superblock. Only the version 2 superblock supports the following features:

- Access Control Lists (ACLs)

- Sun StorEdge QFS shared file system

- `md` devices in Sun StorEdge QFS or Sun SAM-QFS (`ma`) file systems

- Dual-sized disk allocation units (DAUs) on `mm` devices

The Sun StorEdge QFS 4.1 and 4.2 releases support both the version 1 and version 2 superblocks. You can use the `sammkfs`(1M) command to create a version 2 superblock, but you cannot initialize any file systems with version 1 superblocks. In addition, it is not possible to move files from a file system with a version 2 superblock back to a file system with a version 1 superblock.

After you reinitialize a file system, you can use the `qfsrestore`(1M) command to restore files to the new file system from the dump file created in this installation task.

If you are upgrading from a Sun QFS 4.0 system, note that the Sun StorEdge QFS 4.0 file system allowed you to initialize file systems with either a version 1 or a version 2 superblock. If you want to reinitialize any of the file systems that have a version 1 superblock, and remake them with a version 2 superblock, back up these file systems now.

Note - The Sun StorEdge QFS 4.2 software does not allow you to initialize a file system with a version 1 superblock. The Sun StorEdge QFS 4.2 file system only allows you to initialize file systems with the version 2 superblock.

### To Back Up Each File System

1. (Optional) Become superuser from a console connection.

If you have not already logged in as `root`, do so now.

2. Use the `boot`(1M) command to boot the system in single-user mode.

For example:

    # boot -s

3. Use the `mount`(1M) command to mount the Sun StorEdge QFS file system.

For example:

    # mount /qfs1

4. Use the `qfsdump`(1M) command to back up the file data and metadata of each Sun StorEdge QFS file system.

The `qfsdump`(1M) command dumps file names, inode information, and file data. The destination of the `qfsdump`(1M) output (generally a file) must be as large or larger than the Sun StorEdge QFS file system you are backing up. The destination location must have enough space (disk or tape) to hold the amount of file data and metadata you are dumping. For more information about using the `qfsdump`(1M) command, see Establishing Periodic Dumps Using qfsdump(1M) or see the `qfsdump`(1M) man page.

Dump each file system to a location outside of the Sun StorEdge QFS file system. For more information, see the `qfsdump`(1M) man page.

For example, if you have a file system named `qfs1` (mounted at `/qfs1`) that you want to back up, your choices are as follows:

a. You can write the `qfsdump`(1M) output to a tape device.

CODE EXAMPLE 3-2 shows how to write to a tape in device `/dev/rmt/1cbn`.

CODE EXAMPLE 3-2 Writing `qfsdump` (1M) Output to a Tape Device
    # cd /qfs1
    # qfsdump -f /dev/rmt/1cbn

b. You can write the `qfsdump`(1M) output to a file in a UFS file system

CODE EXAMPLE 3-3 shows how to write to a file in a UFS file system.

CODE EXAMPLE 3-3 Writing `qfsdump` (1M) Output to a File in the UFS File System
    # cd /qfs1
    # qfsdump -f /save/qfs/qfs1.bak

c. You can initialize a new Sun StorEdge QFS file system, using a Sun StorEdge QFS 4.2 release, and perform the `qfsrestore`(1M) directly into that new Sun StorEdge QFS file system.

This alternative is applicable only if you already have the Sun StorEdge QFS software installed and operational as a file system somewhere in your environment. Pursuing this alternative assumes that you want to use the features supported by the Sun StorEdge QFS 4.2 release and the version 2 superblock.

For example, assume that you want to write the dump file into a second Sun StorEdge QFS file system called `qfs2` (mounted at `/qfs2`). Make sure that you initialized the `qfs2` file system using Sun StorEdge QFS 4.2 software. CODE EXAMPLE 3-4 shows how to accomplish this using commands.

CODE EXAMPLE 3-4 Writing `qfsdump` (1M) Output to a Sun StorEdge QFS File System
    # mount /qfs2
    # cd /qfs1
    # qfsdump -f - | (cd /qfs2; qfsrestore -f -)

5. Repeat these steps for each Sun StorEdge QFS file system in your environment.

For more information about backing up your file systems, see the Sun QFS, Sun SAM-FS, and Sun SAM-QFS Disaster Recovery Guide.

##

(Optional) Unsharing the File Systems

Perform this task if your Sun StorEdge QFS file systems are NFS shared file systems.

### To Unshare the File Systems

Use the `unshare`(1M) command on the Sun StorEdge QFS file system.

For example, the following command unshares the `qfs1` file system:

    # unshare /qfs1

##

Unmounting the File Systems

There are several ways to unmount a file system. Any of the following methods can accomplish this task. The easiest method is presented first. After the file system is unmounted, you can proceed to Removing Existing Sun StorEdge QFS Software.

### To Unmount Using the `umount`(1M) Command

Using the `umount`(1M) command, unmount each Sun StorEdge QFS file system.

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

### To Unmount Using the `fuser`(1M), `kill`(1), and `umount`(1M) Commands

If `umount`(1M) is not successful, it might be because you or another user are using files or because you or another user have changed to directories in the file system.

1. Use the `fuser`(1M) command to determine whether or not any processes are still busy.

For example, the following command queries the `qfs1` file system:

    # fuser -uc /qfs1

2. If any processes are still busy, use the `kill`(1M) command to terminate them.

3. Using the `umount`(1M) command, unmount each Sun StorEdge QFS file system.

### To Unmount by Editing the `/etc/vfstab` File and Rebooting

1. Edit the`/etc/vfstab` file.

For all Sun StorEdge QFS file systems, change the Mount at Boot field from `yes` or `delay` to `no`.

2. Reboot your system.

### To Unmount a Sun StorEdge QFS Shared File System

Use the instructions in the Sun StorEdge QFS and Sun StorEdge SAM-FS File System Administration Guide for unmounting a Sun StorEdge QFS shared file system.

##

Removing Existing Sun StorEdge QFS Software

The following procedures show how to remove Sun StorEdge QFS software from a release prior to 4.2.

### To Remove Software From a 4.1 Release

1. Use the `pkginfo`(1) command to determine which Sun StorEdge QFS software packages are installed on your system.

For example:

    # pkginfo | grep qfs

2. Use the `pkgrm`(1M) command to remove the existing Sun StorEdge QFS software.

You must remove all existing Sun StorEdge QFS packages before installing the new packages. If you are using any optional Sun StorEdge QFS packages, you should make sure that you remove these packages before removing the main `SUNWqfs` packages. The install script prompts you to confirm several of the removal steps.

The following example command removes the `SUNWqfsu` and the `SUNWqfsr` packages:

    # pkgrm SUNWqfsu SUNWqfsr

Note - The `SUNWqfsr` package must be the last package removed. The 4.1 release does not include any localized software packages.

### To Remove Software From a 4.0 Release

1. Use the `pkginfo`(1) command to determine which Sun StorEdge QFS software packages are installed on your system.

For example:

    # pkginfo | grep qfs

2. Use the `pkgrm`(1M) command to remove the existing Sun StorEdge QFS software.

You must remove all existing Sun StorEdge QFS packages before installing the new packages. If you are using any optional Sun StorEdge QFS packages, make sure that you remove these packages before removing the main `SUNWqfs` package. The install script prompts you to confirm several of the removal steps.

The following example command removes the `SUNWcqfs`, the `SUNWfqfs`, and the `SUNWjqfs` localized packages:

    # pkgrm SUNWcqfs SUNWfqfs SUNWjqfs SUNWqfs

Note - The `SUNWqfs` package must be the last package removed.

##

Adding the Packages

The Sun StorEdge QFS software packages use the Sun Solaris packaging utilities for adding and deleting software. The `pkgadd`(1M) command prompts you to confirm various actions necessary to upgrade the Sun StorEdge QFS package.

During the installation, the system detects the presence of conflicting files and prompts you to indicate whether or not you want to continue with the installation. You can go to another window and copy the files you want to save to an alternate location.

### To Add the Packages

1. Use the `cd`(1) command to change to the directory where the software package release files reside.

When you completed your preinstallation tasks, you obtained the release files as described in Obtaining the Release Files. Use the `cd`(1) command to change to the directory that contains the release files. Changing to the appropriate directory differs, depending on your release media, as follows:

- If you downloaded the release files, change to the directory to which you downloaded the files.

- If you obtained the release files from a CD-ROM, use one of the following commands:

- If you are installing the software on a Solaris 2.8 platform, use the following command:

    # cd /cdrom/cdrom0/2.8

- If you are installing the software on a Solaris 2.9 platform, use the following command:

    # cd /cdrom/cdrom0/2.9

2. Use the `pkgadd`(1M) command to upgrade the `SUNWqfsr` and `SUNWqfsu` packages.

For example:

    # pkgadd -d . SUNWqfsr SUNWqfsu

3. Enter `yes` or `y` as the answer to each of the questions.

4. (Optional) Use the `pkgadd`(1M) command to add one or more localized packages.

Perform this step only if you want to install the packages localized for Chinese, French, or Japanese. CODE EXAMPLE 3-5 shows the commands to use to install the localized packages.

CODE EXAMPLE 3-5 Using the `pkgadd` (1M) Command to Install Localized Packages
    # pkgadd -d SUNWcqfs
    # pkgadd -d SUNWfqfs
    # pkgadd -d SUNWjqfs

##

Updating the License Keys

A license key is required to run the Sun StorEdge QFS software. For information about license keys, see Obtaining a Software License Key.

The Sun StorEdge QFS file system uses an encrypted license key. The license key consists of an encoded alphanumeric string.

### (Optional) To License the Sun StorEdge QFS Software

You do not need to perform this procedure if you are upgrading from a Sun StorEdge QFS 4.0 or 4.1 release unless you also are adding features or equipment to your environment that would change your license. If you are not adding equipment, the system copies your 4.0 or 4.1 license to the correct location when the upgrade is complete.

1. Verify whether the license file exists.

The license file is as follows:

`/etc/opt/SUNWsamfs/LICENSE.4.2`

2. If the `/etc/opt/SUNWsamfs/LICENSE.4.2` file does not exist, create it.

3. Starting in column one, place the license key you have obtained from your ASP or from Sun Microsystems on the first line in the `/etc/opt/SUNWsamfs/LICENSE.4.2` file.

The key must start in column one. No other keywords, host IDs, comments, or other information can appear in the`/etc/opt/SUNWsamfs/LICENSE.4.2` file.

The license keys allow the system to run indefinitely unless you were issued a temporary license. Use the `samcmd`(1M) `l` command to determine whether you were issued a temporary license.

##

(Optional) Enabling the SAM-QFS Manager

Perform this task if you want to be able to use the SAM-QFS Manager.

The SAM-QFS Manager is an online interface to Sun StorEdge QFS that enables you to configure many of the components in a Sun StorEdge QFS environment. You can use this tool to control, monitor, configure, and reconfigure the environment's components.

For information about enabling the SAM-QFS Manager, see (Optional) Enabling the SAM-QFS Manager.

##

Verifying the License and `mcf` Files

The following files exist on your Sun StorEdge QFS server:

- `/etc/opt/SUNWsamfs/LICENSE.4.2`

- `/etc/opt/SUNWsamfs/mcf`

The procedures in this task show you how to verify the correctness of these files.

### To Verify the License File

1. Use the `samd`(1M) `config` command to initialize the Sun StorEdge QFS software.

For example:

    # samd config

2. Enter the `samcmd`(1M) `l` (lowercase L) command to verify the license file.

The `samcmd`(1M) output includes information about features that are enabled. If the output you receive is not similar to that shown in CODE EXAMPLE 3-6, return to Updating the License Keys.

CODE EXAMPLE 3-6 Using `samcmd` (1M)
    # samcmd l
    License information samcmd     4.2      Fri Aug 27 16:24:12 2004
    hostid = xxxxxxx
    License never expires
    Fast file system feature enabled
    QFS stand alone feature enabled
    Shared filesystem support enabled
    SAN API support enabled

### To Verify the `mcf` File

Enter the `sam-fsd`(1M) command to verify the `mcf` file.

Examine the output for errors, as follows:

- If your `mcf` file is free from syntax errors, the `sam-fsd`(1M) output is similar to that shown in CODE EXAMPLE 3-7. It contains information about the file systems and other system information.

CODE EXAMPLE 3-7 `sam-fsd` (1M) Output Showing No Errors
    # sam-fsd
    Trace file controls:
    sam-amld      off
    sam-archiverd off
    sam-catserverd off
    sam-fsd       off
    sam-rftd      off
    sam-recycler  off
    sam-sharefsd  off
    sam-stagerd   off
    sam-serverd   off
    sam-clientd   off
    sam-mgmt      off
    License: License never expires.

- If your `mcf` file contains syntax or other errors, however, it notes the errors in its output.

If your `mcf` file has errors, refer to Defining the Sun StorEdge QFS Configuration By Creating the mcf File and to the `mcf`(4) man page for information about how to create this file correctly.

Note - If you change the `mcf` file after the Sun StorEdge QFS file system is in use, you must convey the new `mcf` specifications to the Sun StorEdge QFS software. For information about propagating `mcf` file changes to the system, see the Sun StorEdge QFS and Sun StorEdge SAM-FS File System Administration Guide.

##

(Optional) Modifying the `/etc/vfstab` File

Perform this task if you modified the `/etc/vfstab` file in Unmounting the File Systems.

### To Modify the `/etc/vfstab` File

Edit this file again, and change the Mount at Boot field for all Sun StorEdge QFS file systems from `no` to `yes` or `delay`.

##

(Optional) Reinitializing and Restoring the File Systems

In this task, you reinitialize your file systems and restore the saved data into the new file systems. This task completes the process initiated in (Optional) Backing Up Existing File Systems. To accomplish this, use the `sammkfs`(1M) and `qfsrestore`(1M) commands on each file system.

Note - The Sun StorEdge QFS 4.2 software does not allow you to initialize a file system with a version 1 superblock. The Sun StorEdge QFS 4.2 file system only allows file systems to be initialized with the version 2 superblock. If you are upgrading from 4.0 using a version 1 superblock, be aware that issuing a 4.2 `sammkfs`(1M) command at this point reinitializes your file system with a version 2 superblock.

### To Reinitialize and Restore the File Systems

1. Use the `samfsinfo`(1M) command to retrieve information about the file system.

You can examine the output from the `samfsinfo`(1M) command to determine the DAU size specified on the `sammkfs`(1M) command when the file system was created. The DAU size is in the `samfsinfo`(1M) output. Use this DAU size again when you perform Step 2.

2. Use the `sammkfs`(1M) command to initialize a new Sun StorEdge QFS file system.

The following example `sammkfs`(1M) command reinitializes a file system named `qfs1` with Sun StorEdge QFS 4.2 feature capabilities:

    # sammkfs qfs1

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

3. Use the `qfsrestore`(1M) command to restore the dumped data into the new file system.

For example, the commands in CODE EXAMPLE 3-8 assume that you have a file system named `qfs1` (mounted at `/qfs1`) that you want to back up from files dumped to `qfs1.bak`, which exists outside of the Sun StorEdge QFS file system:

CODE EXAMPLE 3-8 Using `qfsrestore` (1M) to Restore Files into the New File System
    # cd /qfs1
    # qfsrestore -f /save/qfs/qfs1.bak

##

(Optional) Checking the File System

Perform this task if you did not perform (Optional) Reinitializing and Restoring the File Systems.

Use the `samfsck`(1M) command to check your existing file systems for inconsistancies.

Do this for each Sun StorEdge QFS file system.

##

Mounting the File Systems

Use the `mount`(1M) command to mount your Sun StorEdge QFS file system.

### To Mount the File System

Use the `mount`(1M) command to mount the file systems.

In the following example, `qfs1` is the name of the file system to be mounted:

    # mount qfs1

##

(Optional) Recompiling API-Dependent Applications

If you are running applications that use the Sun StorEdge QFS application programming interface (API), you need to complete this task.

Because file headers, the calling sequence, and other elements of the API can change from release to release, you should recompile all applications that depend on the API at this time.

| Caution - Failure to recompile API-dependent applications at this point can cause your applications to generate unexpected results.

Copyright © 2004, Sun Microsystems, Inc. All rights reserved.