C H A P T E R 5

Sun StorEdge SAM-FS Upgrade Procedure

This chapter explains how to upgrade a server to a new release of the Sun StorEdge SAM-FS software. Use this procedure if you are upgrading your Sun StorEdge SAM-FS environment. 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

- Stopping the Sun StorEdge SAM-FS File System

- (Optional) Unsharing the File Systems

- Unmounting the File System

- Removing Existing Sun StorEdge SAM-FS Software

- Adding the Packages

- Restoring File Changes (inquiry.conf and samst.conf)

- Updating the License Keys

- (Optional) Enabling the SAM-QFS Manager

- Verifying the License, mcf, archiver.cmd, and stager.cmd 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

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

- Server Requirements

- Solaris Operating System Requirements

- Verifying Disk Space

- (Optional) Verifying Archive Media

- 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 under the following conditions:

- You are currently using a version 1 superblock with a Sun SAM-FS 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 `samfsdump`(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 File Systems

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

CODE EXAMPLE 5-1 Using `samfsinfo` (1M)
    # samfsinfo samfs4
    samfsinfo: filesystem samfs4 is mounted.
    name:     samfs4       version:     2
    time:     Sat Sep 20 08:24:34 2003
    count:    1
    capacity:      04b00000          DAU:         16
    space:         02e22ff0
    ord  eq   capacity      space   device
      0  41   04b00000   02e22ff0   /dev/dsk/c9t50020F2300010570d0s1

### Using the Version 1 and Version 2 Superblocks

The Sun StorEdge SAM-FS 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)

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

The Sun StorEdge SAM-FS 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 `samfsrestore`(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 SAM-FS 4.0 system, note that the Sun StorEdge SAM-FS 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 SAM-FS 4.2 software does not allow you to initialize a file system with a version 1 superblock. The Sun StorEdge SAM-FS 4.2 file system only allows you to initialize file systems with the version 2 superblock.

### To Back Up File Systems

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

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

2. Make sure that all files are archived.

The following example assumes that `sam1` is the mount point of the file system. You can complete this step by entering a command similar to the following:

    # sfind /sam1 ! -type d ! -archived > /tmp/notarchived.list

The preceding command finds all files that are not archived and sends the output to a file. Depending on the size of your file system, this command can take a long time to complete.

Examine this command's output. The files in this output are those that have not been archived. If you want any of these files to appear in the dump file, archive them now before you proceed to the next step. Alternatively, you can use the `-u` option to the `samfsdump`(1M) command to dump unarchived data if you suspect some files have not yet been archived. The `-u` option can create very large dump files, however, so you need to weigh space considerations when using this option.

3. Use the `samfsdump`(1M) command to back up each Sun StorEdge SAM-FS file system's metadata.

Dump each file system's metadata to a location outside the Sun StorEdge SAM-FS file system.

CODE EXAMPLE 5-2 assumes that you have a file system mounted at `/sam1` that you want to back up to `samfs1.dump`, which exists outside of the Sun StorEdge SAM-FS file systems.

CODE EXAMPLE 5-2 Using `samfsdump` (1M)
    # cd /sam1
    # samfsdump -f /csd_dump_dir/samfs1.dump

The `samfsdump`(1M) command dumps file names and inode information, not data. For more information, see the `samfsdump`(1M) man page.

You must back up the metadata information for each file system, so repeat the preceding steps for each file system in your Sun StorEdge SAM-FS environment.

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

##

Stopping the Sun StorEdge SAM-FS File System

The procedure in this task shows how to halt Sun StorEdge SAM-FS operations.

### To Stop the File System

1. Use the `samcmd`(1M) idle command to idle the drives in your system.

This step enables the archiver, stager, and other processes to complete current operations. Use this command in the following format:

    samcmd idle eq

For eq, specify the Equipment Ordinal of a device defined in your `mcf` file.

You can also idle the drives by using the `samu`(1M) operator utility. For more information about the `samcmd`(1M) command, see the `samcmd`(1M) man page.

Repeat this step for each removable media drive eq configured in your `mcf` file:

2. (Optional) Use the `samcmd`(1M) `aridle` command to idle the archiver.

Perform this step only if you are upgrading from a Sun StorEdge SAM-FS 4.0 system.

For example:

    # samcmd aridle

3. Use the `samd`(1M) `stop` command to stop all operations.

For example:

    # samd stop

##

(Optional) Unsharing the File Systems

Perform this task if your Sun StorEdge SAM-FS file systems are NFS shared file systems.

### To Unshare the File Systems

Use the `unshare`(1M) command on the Sun StorEdge SAM-FS file system.

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

    # unshare samfs1

##

Unmounting the File System

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 toRemoving Existing Sun StorEdge SAM-FS Software.

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

Using the `umount`(1M) command, unmount each Sun StorEdge SAM-FS 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 `samfs1` file system:

    # fuser -uc /samfs1

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 SAM-FS file system.

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

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

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

2. Reboot your system.

##

Removing Existing Sun StorEdge SAM-FS Software

This task shows how to remove Sun StorEdge SAM-FS 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 SAM-FS packages are installed on your system.

For example:

    # pkginfo | grep sam

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

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

The following example command removes the `SUNWsamfsu` and the `SUNWsamfsr` packages:

    # pkgrm SUNWsamfsu SUNWsamfsr

Note - The `SUNWsamfsr` 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 SAM-FS packages are installed on your system.

For example:

    # pkginfo | grep sam

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

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

The following example command removes the `SUNWcsamf`, the `SUNWfsamf`, and the `SUNWjsamf` localized packages in addition to the `SUNWsamfs` package:

    # pkgrm SUNWcsamf SUNWfsamf SUNWjsamf SUNWsamfs

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

##

Adding the Packages

The Sun StorEdge SAM-FS 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 packages.

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 `SUNWsamfsr` and `SUNWsamfsu` packages.

For example:

    # pkgadd -d . SUNWsamfsr SUNWsamfsu

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

When you install `SUNWsamfsr` and `SUNWsamfsu`, the system asks you if you want to define an administrator group. Select `y` to accept the default (no administrator group), or select `n` if you want to define an administrator group. You can use the `set_admin`(1M) command to reset permissions on certain commands later. For more information, see the `set_admin`(1M) man page.

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 5-3 shows the commands to use to install the localized packages.

CODE EXAMPLE 5-3 Using the `pkgadd` (1M) Command to Install Localized Packages
    # pkgadd -d SUNWcsamf
    # pkgadd -d SUNWfsamf
    # pkgadd -d SUNWjsamf

5. Examine `/tmp/SAM_install.log` .

File `/tmp/SAM_install.log` is the Sun StorEdge SAM-FS log file.

This file should show that the `pkgadd`(1M) command added the `SUNWsamfsr` and `SUNWsamfsu` software packages. Make sure that it also installed Sun StorEdge SAM-FS `samst` driver. If all files installed properly, the following message appears:

    Restarting the sysevent daemon

Note - The tools package, `SUNWsamtp`, is available separately. Contact your Sun sales representative for information about obtaining the 4.2 version of the `SUNWsamtp` package.

##

Restoring File Changes (`inquiry.conf` and `samst.conf`)

Sun Microsystems does not guarantee correct operation with peripherals other than those included in the `/opt/SUNWsamfs/examples/inquiry.conf` file supplied with the release. The installation script compares this file with an existing one, if any, in `/etc/opt/SUNWsamfs`. CODE EXAMPLE 5-4 shows the warning message issued if these files differ.

CODE EXAMPLE 5-4 Warning Message for Differing `inquiry.conf` Files
    inquiry.conf has been updated.
    /opt/SUNWsamfs/examples/inquiry.conf is the latest version;
    please add your changes and copy this file to
    /etc/opt/SUNWsamfs/inquiry.conf

If you have modified `/kernel/drv/samst.conf`, you need to merge any changes to it that might be needed for your configuration. The installation script compares this file with an existing one, if any, in `/kernel/drv/samst.conf`. The exact error message issued if the files differ depends on your Sun Solaris OS level. CODE EXAMPLE 5-5 shows the beginning of the warning message issued if these files differ.

CODE EXAMPLE 5-5 Warning Messages for Differing `samst.conf` Files
    samst.conf has been updated.
    /opt/SUNWsamfs/examples/samst.conf is the latest version;
    please add your changes and copy it to /kernel/drv/samst.conf

##

Updating the License Keys

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

The Sun StorEdge SAM-FS software uses encrypted license keys. The license keys consist of encoded alphanumeric strings. You receive one or more license keys depending on the system configuration and the products being licensed.

### (Optional) To License the Sun StorEdge SAM-FS Software

You do not need to perform this procedure if you are upgrading from a Sun StorEdge SAM-FS 4.0 or 4.1 release unless you are also added to or changing the equipment in your enviroment that would change your license. If you are not adding equipment, the system copies your 4.0 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 SAM-FS that enables you to configure many of the components in a Sun StorEdge SAM-FS 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, `mcf`, `archiver.cmd`, and `stager.cmd` Files

The following files exist on your Sun StorEdge SAM-FS server:

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

- `/etc/opt/SUNWsamfs/mcf`

The following additional files can also exist on your Sun StorEdge SAM-FS server:

- `/etc/opt/SUNWsamfs/archiver.cmd`

- `/etc/opt/SUNWsamfs/stager.cmd`

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 SAM-FS environment.

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 5-6, return to Updating the License Keys.

CODE EXAMPLE 5-6 Using `samcmd` (1M)
    # samcmd l
    License information samcmd     4.2       Fri Aug 27 16:24:12 2004
    License: License never expires.
    hostid = xxxxxxxx
    License never expires
    Remote sam server feature enabled
    Remote sam client feature enabled
    Migration toolkit feature enabled
    Fast file system feature enabled
    Data base feature enabled
    Foreign tape support enabled
    Segment feature enabled
    Shared filesystem support enabled
    SAN API support enabled
    Robot type ATL 2640, P1000, or Sun L1000 Library is present and licensed
        0 tp slots not licensed
        30 lt slots present and licensed
    Robot type STK ACSLS Library is present and licensed
        0 tp slots not licensed
        500 sg slots present and licensed
        500 li slots licensed

### To Verify the `mcf` File

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

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

CODE EXAMPLE 5-7 Example `sam-fsd` (1M) Output
    # sam-fsd
    13: /dev/dsk/c1t1d0s0   10      md      samfs1  on      /dev/rdsk/c1t1d0s0
     *** Error in line 13: Equipment name '/dev/dsk/c1t1d0s0' already in use by eq 10
    72: /dev/rmt/3cbn       45      ug      l1000   on
     *** Error in line 72: Equipment name '/dev/rmt/3cbn' already in use by eq 44
    2 errors in '/etc/opt/SUNWsamfs/mcf'
    sam-fsd: Read mcf /etc/opt/SUNWsamfs/mcf failed.

If your `mcf` file has errors, refer to Defining the Sun StorEdge SAM-FS 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 SAM-FS file system is in use, you must convey the new `mcf` specifications to the Sun StorEdge SAM-FS 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) To Verify the `archiver.cmd` File

Perform this step if you have an `archiver.cmd` file. If you do not have an `archiver.cmd` file, and you are using the archiver's defaults, you do not need to perform this step.

(Optional) Enter the `archiver`(1M) -`lv` (lowercase L) command to verify the `archiver.cmd` file.

The command is as follows:

    # archiver -lv

The output from this command can be quite lengthly. Examine it and verify that the archiving directives are as expected. If you have questions, see (Optional) Creating the archiver.cmd File and see the `archiver.cmd`(4) man page.

##

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

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

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

Edit this file again, and change the Mount at Boot field for all Sun StorEdge SAM-FS 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 `samfsrestore`(1M) commands on each file system.

Note - The Sun StorEdge SAM-FS 4.2 software does not allow you to initialize a file system with a version 1 superblock. The Sun StorEdge SAM-FS 4.2 file system allows file systems to be initialized only with the version 2 superblock. If you are upgrading from 4.0 using version 1 superblocks, be aware that using 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 SAM-FS file system.

The following example `sammkfs`(1M) command reinitializes a file system named `samfs1` with Sun StorEdge SAM-FS 4.2 feature capabilities.

    # sammkfs samfs1

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

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

CODE EXAMPLE 5-8 assumes that you have a file system named `samfs1` (mounted at `/samfs1`) that you want to back up from files dumped to `samfs1.bak`, which exists outside of the Sun StorEdge SAM-FS file system.

CODE EXAMPLE 5-8 Using `samfsrestore` (1M)
    # cd /samfs1
    # samfsrestore -f /save/samfs/samfs1.bak

##

(Optional) Checking the File System

If you did not perform (Optional) Reinitializing and Restoring the File Systems, you are encouraged to complete this task.

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

Do this for each Sun StorEdge SAM-FS 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, `samfs1` is the name of the file system to be mounted:

    # mount samfs1

##

(Optional) Recompiling API-Dependent Applications

If you are running applications that use the Sun StorEdge SAM-FS 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.