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

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:


(Optional) Backing Up Existing File Systems

Perform this task under the following conditions:

The following sections explain the differences between these two superblocks and present the procedure for backing up your 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:

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.




procedure icon  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.


procedure icon  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.


procedure icon  To Unshare the File Systems

single-step bulletUse 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.


procedure icon  To Unmount Using the umount(1M) Command

single-step bulletUsing 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.


procedure icon  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.


procedure icon  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.


procedure icon  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.




procedure icon  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.


procedure icon  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:

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.


procedure icon  (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:

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

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


procedure icon  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


procedure icon  To Verify the mcf File

single-step bulletEnter 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.




procedure icon  (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.

single-step bullet(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.


procedure icon  To Modify the /etc/vfstab File

single-step bulletEdit 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.




procedure icon  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.

single-step bulletUse 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.


procedure icon  To Mount the File System

single-step bulletUse 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 icon

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