C H A P T E R 3

Performing Operational Tasks

This chapter presents topics related to file system operations. This chapter contains the following sections:

- Viewing Files and File Attributes

- Propagating Configuration File Changes to the System

- Setting Up Mount Parameters

- Unmounting a File System

- Adding Disk Cache to a File System

- Re-creating a File System

##

Viewing Files and File Attributes

The attributes specific to Sun StorEdge QFS file systems include both user settings and general file states. This section describes these characteristics and describes how to view them using the `sls` command.

### File Attributes and File States

The user-specified attributes of a file and its system-specified states are stored in the file's inode. You can use the `sls`(1) `-D` command to display these inode attributes. For more information about `sls`(1) options, see the `sls`(1) man page.

A user can specify the following commands to set attributes:

- `archive`(1)

- `ssum`(1)

- `release`(1)

- `segment`(1)

- `setfa`(1)

- `stage`(1)

Users can set attributes from within applications by specifying the following application programming interface (API) routines:

- `sam_archive`(3)

- `sam_release`(3)

- `sam_segment`(3)

- `sam_setfa`(3)

- `sam_ssum`(3)

- `sam_stage`(3)

TABLE 3-1 shows the user-specified attributes that are listed in the inode.

TABLE 3-1 User-Specified File Attributes
File Attribute | Description
--- | ---
`setfa -D` | Marks the file for direct I/O.
`setfa -g` n | Marks the file for allocation on striped group n.
`setfa -s` m | Marks the file for allocation with a stripe width of m.

Note - There are a number of additional user-specified file attributes that are specific to Sun StorEdge SAM-FS archiving functionality. See the Sun StorEdge SAM-FS File System Configuration and Administration Guide for more information.

You can set the attributes shown in TABLE 3-1 on both files and directories. After directory attributes are set, files that are created in the directory inherit all the directory attributes. Files created before an attribute is applied to the parent directory do not inherit directory attributes.

If you have purchased the optional WORM-FS package, you can also apply WORM (write once read many) attributes to a file, and set the file's retention period. See Configuring WORM-FS File Systems for details.

### Displaying File Information

The Sun StorEdge QFS `sls`(1) command extends the standard UNIX `ls`(1) command and provides more information about a file. CODE EXAMPLE 3-1 shows detailed `sls`(1) command output that displays the inode information for file `hgc2`.

CODE EXAMPLE 3-1 `sls` (1) Output in a SAM-QFS Environment
    # sls -D hgc2
    hgc2:
      mode: -rw-r--r--  links:   1  owner: root      group: other
      length:     14971  admin id:      0  inode:       30.5
      archdone;
      segments 3, offline 0, archdone 3, damaged 0;
      copy 1: ---- Jun 13 17:14     2239a.48   lt MFJ192
      copy 2: ---- Jun 13 17:15      9e37.48   lt AA0006
      access:      Jun 13 17:08  modification: Jun 13 17:08
      changed:     Jun 13 17:08  attributes:   Jun 13 17:10
      creation:    Jun 13 17:08  residence:    Jun 13 17:08

#### About the `sls`(1) Output

TABLE 3-2 describes the meaning of each row of `sls`(1) output shown in CODE EXAMPLE 3-1.

Note - Lines that pertain to archiving only appear in `sls`(1) output only in a Sun StorEdge SAM-FS environment.

TABLE 3-2 `sls` (1) Output Explanation
Line Number | Tag | Content
--- | --- | ---
1 | `mode:` | The file's mode and permissions, the number of hard links to the file, the owner of the file, and the group to which the owner belongs.
2 | `length:` | The file's length in bytes, the file's admin ID number, and the file's inode number. By default, the admin ID number is 0. If this number is greater than 0, it indicates the file's accounting category for counting files and blocks. You can set this number to a value greater than 0 even when file system quotas are not enabled on this file system. For information about file system quotas, see Administering File System Quotas. The inode number is a two-part number that contains the inode number itself, followed by a period (.), followed by the inode generation number.
3 | `archdone;` | The file attributes specific to the file. For more information about this line, see the `sls`(1) man page.
4 | `segments` | The segment index information. This line does not appear unless the file is a segment index. The general format for this line is as follows: `segments` n`,` `offline` o`,` `archdone` a`,` `damaged` d`;` `segments` n shows the total number of data segments for this file. In this example, there are 3. `offline` o shows the number of data segments offline. In this example, there are no offline segments. `archdone` a shows the number of segments for which the archiving requirements have been met. In this example, there are 3. `damaged` d shows the number of damaged segments. In this example, there are no damaged segments.
5, 6 | `copy 1:, copy 2:` | Archive copy lines. The `sls`(1) command displays one archive copy line for each active or expired archive copy. The four positions in this line indicate the following: 1 - Either an expired or an active entry. An S indicates that the archive copy is expired. That is, the file was modified and this archive copy is a previous version of the file. A U indicates that the copy has been unarchived. Unarchiving is the process by which archive entries for files or directories are deleted. A dash (-) indicates that the archive copy is active and valid. 2 - Whether the archive copy is to be rearchived. An r indicates that the archive copy is scheduled to be rearchived by the archiver. A dash (-) indicates that the archive copy is not to be rearchived by the archiver. 3 - Unused. 4 - Whether the copy is damaged or undamaged. A `D` indicates that the archive copy is damaged. A damaged archive copy is not a candidate for staging. A dash (-) indicates that the archive copy is not damaged. It is a candidate for staging.
|  | The format of the rest of the archive copy line is as follows: The date and time the archive copy was written to the archive media. Two hexadecimal numbers separated by a decimal point (.). The first hexadecimal number (`2239a`) indicates the position of the beginning of the archive file on the cartridge. The second hexadecimal number (`48`) is the file byte offset (divided by 512) of this copy in the archive file. The media type and the volume serial name (VSN) where the archive copy resides.
7 | `access:` | The time the file was last accessed and modified.
8 | `changed:` | The time the file content and the file's attributes were last changed.
9 | `creation:` | The time the file was created and became resident in the file system.

#### About the Retention Line

If you are using the optional WORM-FS package, a retention line will also appear in the `sls`(1) output. The format of the retention line is as follows:

    retention: active retention-period: 3y 0d 0h 0m

This indicates whether a retention period has been set for this file and, if so, what its length is. The `retention-end` date indicates the date on which the retention period expires. For more information about using the WORM-FS feature, see Configuring WORM-FS File Systems.

##

Propagating Configuration File Changes to the System

This section describes how to propagate configuration file changes throughout the system. The procedures describe the propagation of changes for the following files:

- `mcf`(4)

- `defaults.conf`

- `archiver.cmd` file (SAM-QFS file systems only)

- `stager.cmd` file (SAM-QFS file systems only)

- shared hosts file (Sun StorEdge QFS shared and SAM-QFS shared file systems only)

You must perform these procedures under the following circumstances:

- If you update any of these files in order to add, delete, or correct information.

- If you create or update a Sun StorEdge SAM-FS `archiver.cmd`, `defaults.conf`, or `stager.cmd` file after your Sun StorEdge QFS file system is already operational.

The following sections describe these procedures:

- To Change mcf(4) or defaults.conf(4) Information in a Sun StorEdge QFS Sun Cluster Environment

- To Change mcf(4) or defaults.conf(4) File System Information in a SAM-QFS Environment

- To Change mcf(4) or defaults.conf(4) Removable Media Drive Information

- Changing the Shared Hosts File

- To Add New Entries or Change Existing Entries

- To Change Host Names, Reorder Entries, or Insert Entries

### To Change `mcf`(4) or `defaults.conf`(4) Information in a Sun StorEdge QFS Sun Cluster Environment

To change the `mcf`(4) or the `defaults.conf` information for a shared file system that is configured for high availability in a Sun Cluster environment, perform this procedure on all participating nodes in the Sun Cluster system.

1. Use `vi`(1) or another editor to edit the file and change the file system information.

2. If you are changing the `mcf`(4) file, use the `sam-fsd`(1M) command to check the `mcf`(4) file for errors:

    # sam-fsd

If the output from this command shows errors, correct them before proceeding to the next step.

3. Use the `samd`(1M) `config` command to propagate the `mcf`(4) or `defaults.conf` file changes:

    # samd config

For more information about these files, see the `defaults.conf`(4) or `mcf`(4) man pages.

### To Change `mcf`(4) or `defaults.conf`(4) File System Information in a SAM-QFS Environment

1. Use `vi`(1) or another editor to edit the file and change the file system information.

2. If you are changing the `mcf`(4) file, use the `sam-fsd`(1M) command to check the `mcf`(4) file for errors:

    # sam-fsd

If the output from this command shows errors, correct them before proceeding to the next step.

3. If you are removing or changing information related to one or more file systems, issue a `samcmd`(1M) `aridle` command to idle the archiver for each affected file system defined in the `mcf`(4) file.

Use this command in the following format:

    samcmd aridle fs.fsname

For fsname, specify the name of the file system.

4. If you are removing or changing information related to one or more drives, issue a `samcmd`(1M) `idle` command to idle the archiver for each equipment ordinal assigned to each affected drive in the `mcf`(4) file.

Use this command in the following format:

    samcmd idle eq

For eq, specify the Equipment Ordinal number of the drive.

5. Issue the `umount`(1M) command to unmount each file system affected by the changes.

For instructions on unmounting the file system, see Unmounting a File System.

6. Use the `samd`(1M) `config` command to propagate the changes:

    # samd config

7. Use the `mount`(1M) command to remount the file systems you unmounted.

For more information about these files, see the `defaults.conf`(4) or `mcf`(4) man pages.

### To Change `mcf`(4) or `defaults.conf`(4) Removable Media Drive Information

1. Edit the file and change the removable media drive information.

2. If you are changing the `mcf`(4) file, use the `sam-fsd`(1M) command to check the `mcf`(4) file for errors:

    # sam-fsd

If the output from this command shows errors, correct them before proceeding to the next step.

3. If you are removing or changing information related to one or more file systems, issue a `samcmd`(1M) `aridle` command to idle the archiver for each affected file system defined in the `mcf`(4) file.

Use this command in the following format:

    samcmd aridle fs.fsname

For fsname, specify the name of the file system.

4. If you are removing or changing information related to one or more drives, issue a `samcmd`(1M) `idle` command for the Equipment Ordinal number assigned to each affected drive in the `mcf`(4) file.

Use this command in the following format:

    samcmd idle eq

For eq, specify the Equipment Ordinal number of the drive.

5. Use the `samd`(1M) `stop` command to stop all removable media activity:

    # samd stop

6. Use the `samd`(1M) `config` command to propagate the changes and restart the system:

    # samd config

7. Use the `samd`(1M) `start` command to re-start all removable media activity:

    # samd start

For more information about these files, see the `defaults.conf`(4) or `mcf`(4) man pages.

### Changing the Shared Hosts File

You can add new host entries or change existing entries in the shared hosts file without unmounting the file system. To change host names, reorder the entries, or insert an entry, you must first unmount the file system. Use the following procedures to change the shared hosts file.

To Add New Entries or Change Existing Entries

Use this procedure to add new host entries to the end of the shared hosts file or to change columns 2 through 5 of existing entries in the shared hosts file.

1. If you do not know the host that is acting as the metadata server, issue the `samsharefs`(1M) family-set-name command to display the name of the metadata server.

Issue this command from any host that has the file system configured.

For example:

    # samsharefs sharefs1

2. On the metadata server, save the shared hosts file to a temporary working file.

For example:

    # samsharefs sharefs1 > /tmp/file

3. (Optional) Save a copy of the shared hosts file.

For example:

    # cp /tmp/file /var/opt/SUNWsamfs/hosts.date

4. Use `vi`(1) or another editor to edit the temporary working file.

For mounted file systems, you can add new host entries to the end of the file, and you can make changes to columns 2 through 5 for existing entries.

5. Save and close the temporary working file.

6. Copy the temporary working file to the `SUNWsamfs` directory.

For example:

    # cp /tmp/file /var/opt/SUNWsamfs/hosts.sharefs1

7. Apply the new shared hosts file to the file system.

For example:

    # samsharefs -u sharefs1

To Change Host Names, Reorder Entries, or Insert Entries

The procedure for changing host names, reordering entries, or inserting entries in the shared hosts file requires that you unmount the file system.

1. If you do not know the host that is acting as the metadata server, issue the `samsharefs`(1M) `-R` family-set-name command to display the name of the metadata server.

Issue this command from any host that has the file system configured.

For example:

    # samsharefs -R sharefs1

2. Unmount the file system on each participating client, and then on the metadata server.

3. On the metadata server, save the shared hosts file to a temporary working file.

For example:

    # samsharefs -R sharefs1 > /tmp/file

4. (Optional) Save a copy of the shared hosts file.

For example:

    # cp /tmp/file /var/opt/SUNWsamfs/hosts.date

5. Use `vi`(1) or another editor to edit the temporary working file.

6. Save and close the shared hosts file.

7. Copy the new shared hosts file to the `SUNWsamfs` directory.

For example:

    # cp /tmp/file /var/opt/SUNWsamfs/hosts.sharefs1

8. Apply the new shared hosts file to the file system.

For example:

    # samsharefs -uR sharefs1

9. Mount the file system on the metadata server, and then on the clients.

##

Setting Up Mount Parameters

You can mount a Sun StorEdge QFS file system by using the Solaris OS `mount`(1M) command.

Mount parameters are used to manipulate file system characteristics. There are several ways to specify mount parameters. Methods at the top of the hierarchy override methods lower in the hierarchy. You can specify mount options in the following ways, listed in hierarchical order from the top down:

- With the `mount`(1M) command using command line options. Options specified on the Solaris OS `mount`(1M) command line override other options specified in the `/etc/vfstab` file, directives specified in the `samfs.cmd` file, and system default settings.

- As `/etc/vfstab` file settings.

- In the `samfs.cmd` file using directives.

- As system defaults. The default system settings are the configurable settings already defined for your Solaris OS. You can override the system settings with specifications in the `samfs.cmd` file, in the `/etc/vfstab` file, and in the `mount`(1M) command.

You can also specify mount options by using the `samu`(1M) operator utility or the `samcmd`(1M) command. Mount options enabled or disabled in this way persist until the file system is unmounted.

The following subsections describe ways to specify mount options. For information about specific mount options, see Appendix B Mount Options in a Sun StorEdge QFS Shared File System. The Sun StorEdge QFS Installation and Upgrade Guide also includes information about mounting a file system.

### The `mount`(1M) Command

The Solaris OS `mount`(1M) command mounts the file system and enables you to specify settings that override the settings specified in the `/etc/vfstab` file and in the `/etc/opt/SUNWsamfs/samfs.cmd` file. For example, you can specify the stripe width, read-ahead, write-behind, and high and low water marks for disk cache utilization.

One way to use the `mount`(1M) command in conjunction with the `samfs.cmd` file is to use the `samfs.cmd` file as your main location for mount options and to use options on the `mount`(1M) command when experimenting with or tuning your system.

For example, the following command mounts file system `qfs1` at `/work` with `setuid` execution disallowed and `qwrite` enabled. The `qfs1` file system name is the Equipment Identifier. This also appears in the `mcf`(4) file's Equipment Identifier field for this file system. To specify more than one mount option, separate each with a comma.

    # mount -o nosuid,qwrite qfs1 /work

If you are mounting a Sun StorEdge QFS or SAM-QFS shared file system, you must mount the file system on the metadata server first, and then mount the file system on each participating client host. Include the `shared` option with the `mount` command, and remember that the command must be identical on the metadata server and on the participating hosts.

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

### The `/etc/vfstab` File

Each Sun StorEdge QFS file system that is defined in the `mcf`(4) file must have a line in the `/etc/vfstab` Solaris OS system file. This is required for mounting the file system.

The following is an example of a file system line in the `/etc/vfstab` file:

    qfs1    -    /qfs    samfs    -    yes    stripe=0

From left to right, the fields shown indicate the following:

- The file system family set name.

- The file system to `samfsck`(1M).

- The mount point.

- The file system type. This is always `samfs`, even for Sun StorEdge QFS file systems.

- The `samfsck`(1M) pass.

- Mount-at-boot options.

- Mount parameters, separated by commas, without intervening spaces.

The fields in the `/etc/vfstab` file must be separated by either space or tab characters.

The mount parameters field can contain any of the mount parameters listed as arguments to the `-o` option on the `mount_samfs`(1M) man page. These parameters are nearly identical to those that you can specify as directive lines in the`samfs.cmd` file or as arguments to the `-o` option in the `mount`(1M) command. As with the `samfs.cmd` file, you can include specifications for various I/O settings, read-ahead, write-behind, the stripe width, various storage and archive management settings, Qwrite, and other features.

For more information about possible mount parameters, see the `mount_samfs`(1M) man page. For more information about modifying the `/etc/vfstab` file, see the`vfstab`(4) man page.

### The `samfs.cmd` File

The `/etc/opt/SUNWsamfs/samfs.cmd` file enables you to specify mount parameters for all of your Sun StorEdge QFS file systems. This file can be useful when you have multiple file systems configured and you want to specify the same mount parameters for all of them.

Using this file enables you to define all mount parameters in one place in an easily readable format. Directives specified toward the beginning of this file are global directives and apply to all Sun StorEdge QFS file systems. The second part of this file enables you to indicate the specific parameters that you want to apply to each individual file system. The ability to specify the common parameters once, and in only one place, differentiates this file from the `/etc/vfstab` file, in which you must specify all mount parameters for each file system.

The mount parameters that can be specified in the `samfs.cmd` file are nearly identical to those that you can specify in the `/etc/vfstab` file or as arguments to the `-o` option with the `mount`(1M) command. The possible mount parameters you can specify pertain to I/O settings, read-ahead, write-behind, the stripe width, various storage and archive management settings, WORM-FS, Qwrite, and other features. For more information about the mount parameters that can be specified in this file, see the `samfs.cmd`(4) man page.

In the `samfs.cmd` file, directives are written one per line. The file can contain comments, which must begin with a pound character (`#`). Characters that appear to the right of the pound character are treated as comments.

For a directive that applies globally to all file systems, place the line before any `fs =` line. For a directive that is specific to a particular file system, start the line with
`fs =` and place it after all global directives. Directives specific to a particular file system override global directives.

CODE EXAMPLE 3-2 shows a sample `samfs.cmd` file that sets the low and high water marks for disk cache utilization for all file systems and specifies individualized parameters for two specific file systems.

CODE EXAMPLE 3-2 Example `samfs.cmd` File
    low = 50
    high = 75
    fs = samfs1
       high = 65
       writebehind = 512
       readahead = 1024
    fs = samfs5
       partial = 64

The directives in the `samfs.cmd` file override any default system settings, but arguments to the `mount`(1M) command override any directives in this file. Entries in the `/etc/vfstab` file also override directives specified in the `samfs.cmd` file.

For information about the `mount`(1M) command, see the `mount_samfs`(1M) man page. For information about which directives can be entered in the `samfs.cmd` file, see the `samfs.cmd`(4) man page.

##

Unmounting a File System

You can use the Solaris OS `umount`(1M) command to unmount Sun StorEdge QFS file systems.

### To Unmount a Standalone QFS or SAM-QFS File System

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

    # umount /samqfs

Several conditions can be present in a file system at unmounting time. You may want to `unshare`(1M) the file system if it has been shared out for NFS use. After unsharing, try issuing the unmount command a second time. If this fails and it is necessary to unmount the filesystem, use the `-f` option to the `umount`(1M) command. The `-f` option forces a file system to unmount.

For more information on unmounting procedures, see the Sun StorEdge QFS Installation and Upgrade Guide.

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

Follow the instructions in To Unmount a Shared File System.

##

Adding Disk Cache to a File System

To increase the disk cache for a file system, you add disk partitions or disk drives, and then update the `mcf`(4) file and use the `samgrowfs`(1M) command to expand the file system. You do not need to reinitialize or restore the file system.

When making changes to the `mcf`(4) file, be aware of the following:

- You can configure up to 252 disk partitions in a file system.

- To increase the size of a Sun StorEdge QFS file system, you must add at least one new metadata partition. Metadata partitions require an Equipment Type value of `mm`.

- If you want to add new partitions for metadata or for data, add them to the `mcf`(4) file after the existing disk partitions.

- Do not change the Equipment Identifier name in the `mcf`(4) file. If the name in the `mcf`(4) file does not match the name in the superblock, the file system can no longer be mounted. Instead, the following message is logged in`/var/adm/messages`:

    WARNING SAM-FS superblock equipment identifier <id>s on eq <eq> does not match <id> in mcf

### To Add Disk Cache to a File System

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

If the file system is shared, unmount the file system on all client hosts and then on the metadata server. You can then perform the remaining steps in this procedure on the metadata server.

For more information about unmounting a file system, see Unmounting a File System.

2. If you want to rename the file system during this procedure, use the `samfsck`(1M) command with its `-R` and `-F` options to rename the file system.

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

3. Edit the `/etc/opt/SUNWsamfs/mcf` file to add the disk cache.

4. Issue the `sam-fsd`(1M) command to check for errors in the `mcf`(4) file:

    # sam-fsd

If the output from this command shows errors, correct them before proceeding to the next step.

5. Issue the `samd`(1M) `config` command to propagate the `mcf`(4) file changes to the system:

    # samd config

For more information, see the `samd`(1M) man page.

6. Issue the `samgrowfs`(1M) command on the file system that is being expanded.

For example, type the following command to expand file system `samfs1`:

    # samgrowfs samfs1

If you renamed the file system, run the `samgrowfs`(1M) command using the new name. For more information about this command, see the `samgrowfs`(1M) man page.

7. Mount the file system.

For information about mounting a Sun StorEdge QFS file system, see the `mount_samfs`(1M) man page.

8. If the file system is a Sun StorEdge QFS shared file system, edit the `mcf`(4) file on each participating client host to match the metadata server's `mcf` file.

##

Re-creating a File System

In order to do any of the following, you must re-create the file system:

- Change disks or partitions

- Add disks or partitions

- Remove disks or partitions

This section describes this procedure.

### To Back Up and Re-create a File System

1. 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 in your Sun StorEdge QFS environment. Also make sure that you have backup copies of files in the `/etc/opt/SUNWsamfs` directory, files in the `/var/opt/SUNWsamfs` directory, and shared hosts files.

2. 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. If, however, you need to back up your file systems to preserve information created since the last dump file was created, do so now. For information about how to create a dump file using `qfsdump`, see the Sun StorEdge QFS Installation and Upgrade Guide.

3. Unmount the file system.

For instructions, see Unmounting a File System.

4. If you want to rename the file system during this procedure, use the `samfsck`(1M) command with its `-R` and `-F` options.

For more information, see the `samfsck`(1M) man page.

5. Edit the `/etc/opt/SUNWsamfs/mcf` file to add, change, or remove partitions.

For more information, see Adding Disk Cache to a File System.

6. Type the `sam-fsd`(1M) command to check for errors in the `mcf`(4) file:

    # sam-fsd

If the output from this command indicates that there are errors in the `mcf`(4) file, correct them before proceeding to the next step.

7. Issue the `samd`(1M) `config` command to propagate the `mcf`(4) file changes to the system:

    # samd config

For more information, see the `samd`(1M) man page.

8. Issue the `sammkfs`(1M) command to re-create the file system.

For example, the following command creates `samfs10`:

    # sammkfs samfs10

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

For information about mounting a Sun StorEdge QFS file system, see the `mount_samfs`(1M) man page.

10. Issue the `cd`(1) command to change to the mount point of the file system.

11. Use the `qfsrestore`(1M) command, or use File System Manager, to restore each file.

Restore from the dump file you had or from the dump file created in Step 1.

For more information, see the `qfsdump`(1M) man page or the File System Manager online help.

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