8 Documentation Notes

This chapter contains release notes that apply to Tru64 UNIX Version 5.0A documentation. It provides information on the following:

Netscape problem with the Search by Keyword feature (Section 8.1)

System limits documentation (Section 8.2)

AltaVista search (Section 8.3)

Command and Shell User's Guide (Section 8.4)

AdvFS Administration (Section 8.4)

System Configuration and Tuning (Section 8.7)

The mount(8) reference page (Section 8.9)

Online help (Section 8.11)

8.1 Netscape Problem with the Search by Keyword Feature

Netscape on Tru64 UNIX does not handle JavaScript forms correctly. When you use the Reference Pages Search by Keyword feature on the Documentation CD-ROM, the search can fail.

To work around the problem, click in any other window and return to the search window.

This problem does not occur with Netscape or Microsoft Internet Explorer on a Windows PC or Macintosh.

8.2 System Limits Documentation

The system limits information has been moved from the Release Notes to the Tru64 UNIX Version 5.0A Software Product Description (SPD). Any references to this information being in the Release Notes is in error. PDF and PostScript copies of the SPD are located in the /DOCUMENTATION directory on the Tru64 UNIX Version 5.0A Operating System Volume 1 CD-ROM.

8.3 AltaVista CD-ROM Search Might Not Work Correctly with Netscape Communicator

When the Tru64 UNIX Software Documentation CD-ROM is used on a PC for which Internet Explorer is the default browser, the CD-ROM search capability works as documented in the instructions window. This window automatically pops up when you click on the Search button that is available from the main page of the documentation library. The instructions tell you to open Windows Explorer, double click on the icon for the CD-ROM drive, and then double click on search.exe, which automatically loads the search query entry form into the Internet Explorer window.

When the documentation CD-ROM is used on a PC for which Netscape Communicator is the default browser, these instructions might work, but sometimes do not. Problems observed when trying to use AltaVista CD-ROM Search with Netscape Communicator (Version 4.5 or higher) include the following:

An attempt to load the search query entry form (InitPage.html) results in a "browser not found" error.

The search query entry form comes up in a window different from the Netscape browser window.

If the search query entry form does come up in the Netscape browser window, the first search query consistently hangs.

If you encounter one or more of these problems, use the following procedure to work around them:

After launching the AltaVista Search Dispatcher (search.exe), invoke Netscape manually if it is not already running.

Use the File Open option in the Netscape window to find and open the InitPage.html file on the CD-ROM drive. Alternatively, you can type the URL to this file in the Netscape browser's Location: field.

If your first search query takes more than 30 seconds to execute, click on the Stop icon and re-enter the query.

8.4 Command and Shell User's Guide

Table 3-1 of the Command and Shell User's Guide contains an error for the ls command option. The following description for the -R option is incorrect:

-R Lists all entries including hidden files. Without this flag, the ls command does not list the names of entries that begin with a dot (.), such as .profile, .login, and relative pathnames.

This is the description of the -a option. Therefore, it should read as follows:

-a Lists all entries including hidden files. Without this flag, the ls command does not list the names of entries that begin with a dot (.), such as .profile, .login, and relative pathnames.

8.5 Security

The information in Section 19.10.2 of the Security guide describing the binary audit log record format is incomplete and potentially misleading. Do not use this information as a basis for any code.

8.6 DECthreads Is Now the POSIX Threads Library

With this release, DECthreads has been renamed the POSIX Threads Library. The Guide to DECthreads is now the Guide to the POSIX Threads Library.

8.7 System Configuration and Tuning

The following notes pertain to the System Configuration and Tuning manual.

8.7.1 AdvFS Buffer Cache

AdvFS stores recent read and write requests for both file data and metadata in memory buffers. When an application requests a page, AdvFS checks the AdvFS buffer cache for the page, and then checks the UBC. If the page is found in memory, AdvFS reuses the buffer and avoids a disk I/O operation. Buffers that are not reused are eventually recycled for newly referenced pages.

You may be able to improve performance by modifying the size of the AdvFS buffer cache. If your applications reuse data, you can maximize the number of AdvFS buffer cache hits by making the AdvFS buffer cache large enough to hold pages until they are reused. However, increasing the size of the AdvFS buffer cache consumes memory and may cause paging.

If your applications do not reuse I/O, you do not need a large cache size. Also, on very large-memory systems, the AdvFS buffer cache may be too large and may waste memory. You may want to free memory by decreasing the size of the cache in these cases.

The advfs subsystem attribute AdvfsCacheMaxPercent specifies the size of the AdvFS buffer cache. The default value of the AdvfsCacheMaxPercent attribute is 7 percent of physical memory. The minimum value is 1 percent; the maximum value is 30 percent.

To determine if you need to modify the size of the AdvFS buffer cache, you must understand how your applications perform file system I/O. Then, use the advfsstat -b command to check the AdvFS buffer cache hit rate for the specified domain.

After you gather information about how your applications perform file system I/O and run the advfsstat -b command, use the following table to determine if you should modify the size of the AdvFS buffer cache. These recommendations apply only if AdvFS is configured on your system.

Requirement	Tuning Recommendation
AdvFS is configured on your system, but you are not using AdvFS.	Set the value of the `AdvfsCacheMaxPercent` attribute to 1 to minimize the memory allocation to the AdvFS buffer cache.
You are running applications that perform their own buffer caching.	Decrease the value of the `AdvfsCacheMaxPercent` attribute by 1 or 2. Then, use the `advfsstat -b` command to check the hit rate. Continue to decrease only if the hit rate is above 80 percent.
You have a very-large memory system, with a moderate AdvFS load and an AdvFS buffer cache hit rate of more than 80 percent.	In this case, an overly large buffer cache may be wasting memory. You may want to decrease the size of the AdvFS buffer cache. Reduce the value of `AdvfsCacheMaxPercent` by 1 or 2. Then, use the `advfsstat -b` command to check the hit rate. Continue to decrease only if the hit rate is above 80 percent.
You have an AdvFS buffer cache hit rate of more than 80 percent.	You may be able to improve file system performance by increasing the memory available to cache AdvFS pages. To do this, increase the value of the `AdvfsCacheMaxPercent` attribute by 1 or 2. Then, use the `advfsstat -b` command to check the hit rate, and use the `vmstat` command to check for increased paging. Continue to increase the value of `AdvfsCacheMaxPercent` only if you continue to improve the hit rate, without causing the system to page. Use the `vmstat` command to check for paging activity.
You have a low cache hit rate of less than 80 percent.	This may indicate one of the following: The size of the AdvFS cache is insufficient for the load and pages are being recycled (used for a different AdvFS page) from the cache too quickly. In this case, you may want to increase the value of the `AdvfsCacheMaxPercent` attribute by 1 or 2. Applications are mainly writing to new files and are not reusing the cached AdvFS pages. In some cases, increasing the value of the `AdvfsCacheMaxPercent` attribute by 1 or 2 may reduce cache recycling and provide better AdvFS I/O consolidation. (Applies only to Tru64 UNIX Version 4.0F and higher versions.) Use the `advfsstat -b` command to check the hit rate, and use the `vmstat` command to check paging activity. Continue to increase `AdvfsCacheMaxPercent` only if you continue to increase the hit rate, without causing the system to page.

You must reboot the system to use the new value of the AdvfsCacheMaxPercent attribute.

After you size the AdvFS buffer cache, you may want to consider tuning the AdvFS buffer cache hash chains.

8.7.2 AdvFS Buffer Hash Chains

The following information on AdvfsCacheHashSize in the System Configuration and Tuning guide is incorrect:

The last sentence in the When to Tune section states that you should increase the hash chain table if the average number of buffers for each chain is greater than 100. This is incorrect. You should increase the hash chain table if the average number of buffers for each chain is greater than 10.

The first two sentences in the Recommended Values section state that the default value of the AdvfsCacheHashSize attribute is either 8192 KB or 10 percent of the size of the AdvFS buffer cache (rounded up to the next power of 2), whichever is the smallest value and that the minimum value is 1024 KB. This is incorrect. This should read as follows:

The default value of the AdvfsCacheHashSize attribute is either 8192 or 10 percent of the size of the AdvFS buffer cache (rounded up to the next power of 2), whichever is the smaller value. The minimum value is 1024.

The cache hash chain table is used to locate pages of AdvFS file and metadata that are stored in the AdvFS buffer cache. The table has a number of hash chains, which contain buffers (entries) that point to pages of file system data that have already been read into memory. When a page is requested, AdvFS uses a hashing algorithm to identify the hash chain that contains the buffer, and then searches that hash chain for the buffer.

The number of buffers on each hash chain can affect AdvFS performance. Short hash chains contain less buffers to search, which improves lookup speeds and decreases CPU usage.

When the system allocates AdvFS buffers, it spreads them evenly across the available hash chains. AdvFS attempts to use a hash chain size of ten (buffers). However, if the system allocates a large number of AdvFS buffers, each hash chain will contain more than ten buffers. In this case, you may be able to improve performance by increasing the number of hash chains. This will spread the AdvFS buffers across more hash chains and decrease the number of buffers on each hash chain.

Increase the number of hash chains only if there are more than ten buffers on each hash chain. In addition, if the size of your AdvFS buffer cache is less than 640 MB, you do not have to increase the number of hash chains.

To determine the number of buffers on each hash chain, follow these steps:

Determine the total number of AdvFS buffers. Use one of the following methods:
- Examine the AdvFS startup message that displays the number of buffers. At boot time, the system allocates a number of AdvFS buffers and displays a message similar to the following:
```
ADVFS: using 1611 buffers containing 12.58 megabytes of memory
```
- Determine the number of 8 KB pages that can be obtained from the memory allocated to the AdvFS buffer cache. To do this, divide the value of the AdvfsCacheMaxPercent attribute (as a percentage of total physical memory) by 8192.

Divide the number of buffers by the number of hash chains, which is specified by the AdvfsCacheHashSize attribute.

If there are more than 10 buffers on each hash chain, you may want to increase the value of the AdvfsCacheHashSize attribute. Set the attribute to 10 percent of the total number of AdvFS buffers allocated at boot time, up to a maximum of 65,536.

If you later increase the amount of memory available to the AdvFS buffer cache, recalculate the number of buffers on each hash chain. Increase the number of hash chains if there are more than ten buffers on each hash chain.

8.7.3 AdvFS File Domain and Fileset Configuration Guidelines

The guidelines for configuring AdvFS filesets are not accurate in the Version 5.0 System Configuration and Tuning manual.

In Table 9-2, the following AdvFS fileset configuration guidelines are not accurate:

Configure one fileset for each domain

Keep filesets less than 50 GB in size

Additionally, the information in Section 9.3.4.2 is not accurate.

To configure AdvFS file domains and filesets for high availability, high performance, scalability, and ease of management, use the following information and guidelines.

The filesets in a file domain share the disk space in the domain and use the same domain transaction log. Each fileset has its own directory structure, root tag directory, quota files, and frag file.

The optimal AdvFS configuration depends on the requirements of the applications that use the file domains and filesets. Consequently, your AdvFS configuration may consist of different combinations of volumes, file domains, and filesets.

The following file domain guidelines are applicable to most configurations and workloads:

Configure multiple small file domains, instead of a single large file domain
This provides better control over physical resources, improves a fileset's total throughput, and decreases administration time. Multiple domains can also improve availability, because a domain volume failure makes the entire domain unavailable.
For most configurations, the optimal size of a file domain is 20 to 50 GB. This size enables AdvFS administrative commands to run quickly. However, a domain that is larger than 50 GB may provide adequate performance, depending on the application that uses it and the degree of access.

Configure multiple-volume file domains, instead of single-volume file domains
This provides better control over physical resources and improves a fileset's total throughput. Because a volume failure will make the entire domain unavailable, the more volumes in a file domain, the greater the risk that the domain will fail. Therefore, you may want to limit the number of volumes in a file domain to eight, or eliminate this point of failure by mirroring the volumes or by using RAID 5.
See the System Configuration and Tuning manual for more information about configuring file domains.

The optimal number of AdvFS filesets in a file domain depends on the requirements of the applications that use the fileset. In some cases, you may want to configure a single fileset in a file domain. In other cases, you may want multiple filesets in a file domain.

The amount of I/O contention on the volumes in a file domain is the most critical factor for fileset performance. This can occur on large, very busy file domains.

To help you determine how to set up filesets, first identify:

Frequently accessed data

Infrequently accessed data

Specific types of data (for example, temporary data or database data)

Data with specific access patterns (for example, create, remove, read, or write)

Then, use the previous information and the following guidelines to set up filesets:

Configure filesets that contain similar types of files in the same file domain to reduce disk fragmentation and improve performance. For example, do not place small temporary files, such as the output from cron and from news, mail, and Web cache servers, in the same file domain as a large database file.

For applications that perform many file create or remove operations, configure multiple filesets and distribute data across the filesets. This reduces contention on individual directories, the root tag directory, quota files, and the frag file.

Configure filesets used by applications with different I/O access patterns (for example, create, remove, read, or write patterns) in the same file domain. This might help to balance the I/O load.

Additionally, Compaq recommends that you consider future file system needs when setting up file domains and filesets. For example, you may want to set up filesets so that they can accommodate an increase in data without causing the file domain to grow to an unmanageable size.

As part of preventative maintenance and to avoid problems, periodically check for the following:

I/O contention on file domain volumes -- To reduce I/O contention in a multi-volume file domain with more than one fileset, divide it into multiple domains and distribute the filesets across the domains. This enables each volume and domain transaction log to be used by fewer filesets.

File domain that is greater than 50 GB -- Divide a large file domain into multiple domains. Note that a file domain that is larger than 50 GB may provide adequate performance, depending on the application that uses it and the degree of access.

Fileset with a very large number of small files -- This configuration may affect vdump and vrestore commands at times. Dividing the fileset into multiple filesets enables the vdump command to be run simultaneously on each fileset, and decreases the amount of time needed to recover filesets with the vrestore command.

Fileset with many frequently accessed files -- Divide a busy fileset into multiple filesets and distribute the files across the filesets. Use filesets on different domains to reduce log contention caused by many writes or metadata changes.

Large number of files in each fileset directory -- If the fileset is in a file domain that uses the on-disk formats employed by AdvFS prior to Version 5.0 (that is, domain version 3), divide the fileset into multiple filesets and distribute the files across the filesets. Note that the version 4 on-disk format supported by Version 5.0 and later releases greatly improves directory access performance and scalability.

Use the showfdmn command to display information about the file domain size and volumes. See the showfdmn(8) for more information.

Use the showfsets command to display the number of filesets in a domain and the size of a fileset. See showfsets(8) for more information.

8.8 AdvFS Administration Guide

The example in the AdvFS Administration guide that shows how to remove a file from a trashcan is in error. The example should read as follows:

# cd keeper

8.9 Error in the mount(8) Reference Page

The rdonly option listed in the AdvFS and UFS Arguments section of the mount(8) reference page is incorrect. This option does not exist.

To allow read-only access, use the ro option.

8.10 Additional Information for the ifconfig(8) and ifaccess.conf(4) Reference Pages

The following information was omitted from the ifconfig(8) and ifaccess.conf(4) reference pages:

The netstat -I command displays an interface's filter information as set up with the /etc/ifaccess.conf file.

8.11 Online Help

The notes in this section apply to the online help.

8.11.1 SysMan Menu

The notes in this section apply to the online help for the SysMam Menu application.

8.11.1.1 Title Bar Is Incorrect

When you are using the SysMan Menu's online help in the Common Desktop Environment (CDE), the title bar displayed for the help window always displays the name of the first application for which you requested help.

Ignore the title bar. The correct help volume is displayed in the help window and the Volume label at the top of the window correctly identifies the help volume.

8.11.1.2 Help on Item Sometimes Fails

The SysMan Menu's Help On Item buttons provide online help for the selected menu item. When running the SysMan Menu from a PC, from a web browser, or from the SysMan Station, Help On Item for certain tasks fails with an error when trying to access a URL such as the following:

http://your_machine:2301/SYSMAN/suitlet_help/html/en_US.ISO-8859-1/help_application/help_task.html

To avoid this problem, launch the specific task and select the online help within the task itself. You can also run the SysMan Menu on a terminal or on an X11 display (for example, sysman -display host:0.0) and the help is displayed properly.

8.11.2 System Management Station

The notes in this section apply to the online help for the System Management Station (SMS).

8.11.2.1 Some Online Help Does Not Work Until Connected to the Server

The SysMan Station (SMS) client obtains its online help information from the SMS server. A few of the dialog boxes displayed during the initial connection sequence have Help or More Information buttons that do not function properly because a server connection has not yet been established. Specifically, this is a problem with the Welcome, Connecting to, and Failed to connect dialog boxes.

8.11.2.2 Some Links Do Not Work Properly

The following links under Section 2.2, View Window, of the Reference section of the SysMan Station Online Help do not work properly:

ADVFS_Filesystems View

CAA_Applications_(all) View

CAA_Applications_(active) View

Hardware View

Mounted_Filesystems View

Physical_Filesystems View

You can obtain information on these topics by selecting Section 2.2, View Window.

8.11.2.3 Online Help Window Does Not Maximize Automatically

If you open an SMS online help window and minimize it, it does not automatically maximize when you reselect Help from the SMS session. You must manually maximize the Help window to view the new help information.