CMVC FREQUENTLY ASKED QUESTIONS:
HANDLING FILE, RELEASE AND LEVEL EXTRACT PROBLEMS
Document Number TR 29.2323
Lee Perlov, Angel Rivera and Jianren Yang
TeamConnection/CMVC Development
IBM Software Solutions
Research Triangle Park, North Carolina
Copyright (C) 1996,1997 IBM
ii Solving CMVC Release -extract problems
ABSTRACT
This technical report provides answers to frequently asked
questions made by CMVC users with respect to file, release and
level extract requests and methods of diagnosing problems.
ITIRC KEYWORDS
o CMVC
o File -extract
o Release -extract
o Level -extract
o NFS mount
ABSTRACT iii
iv Solving CMVC Release -extract problems
ABOUT THE AUTHORS
LEE R. PERLOV
Mr. Perlov is a Staff Software Engineer in the
TeamConnection/CMVC development group. He started working for
IBM in 1985 in Gaithersburg, Md, working in the Federal Systems
Division on various projects for the United States intelligence
community. He then moved to RTP to work on library development
and support.
Mr. Perlov received a B.S.Acc degree in Accounting from the Uni-
versity of Florida in 1983. He also completed two years of grad-
uate work in the Department of Computer Science at the University
of Florida.
ANGEL RIVERA
Mr. Rivera is an Advisory Software Engineer and team lead for the
CMVC development group; he is also a member of the TeamConnection
development team. He joined IBM in 1989 and since then has
worked in the development and support of library systems.
Mr. Rivera has an M.S. in Electrical Engineering from The Univer-
sity of Texas at Austin, and B.S. in Electronic Systems Engi-
neering from the Instituto Tecnologico y de Estudios Superiores
de Monterrey, Mexico.
JIANREN YANG
Mr. Yang is a Member of Technical Staff with Lucent Technologies
in Cary, NC.
Mr. Yang was a Staff Software Engineer in the TeamConnection /
CMVC department. He worked at several companies (such as
Motorola) before joined IBM in 1995, and until 1997 he worked in
the development and support of both CMVC and TeamConnection pro-
ducts.
Mr Yang has an M.S. in Computer Science from University of
Illinois at Urbana-Champaign (known as UIUC) and B.S. in Computer
Science from Nanjing University, P. R. China.
ABOUT THE AUTHORS v
vi Solving CMVC Release -extract problems
CONTENTS
ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . III
ITIRC KEYWORDS . . . . . . . . . . . . . . . . . . . . . iii
ABOUT THE AUTHORS . . . . . . . . . . . . . . . . . . . . . . V
Lee R. Perlov . . . . . . . . . . . . . . . . . . . . . . . v
Angel Rivera . . . . . . . . . . . . . . . . . . . . . . . v
Jianren Yang . . . . . . . . . . . . . . . . . . . . . . . v
FIGURES . . . . . . . . . . . . . . . . . . . . . . . . . . IX
1.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . 1
1.1 About this and previous technical reports . . . . . . 1
1.2 About CMVC and TeamConnection . . . . . . . . . . . . 2
1.3 Acknowledgements . . . . . . . . . . . . . . . . . . . 2
2.0 OVERVIEW OF POSSIBLE PROBLEMS . . . . . . . . . . . . . 3
2.1 Limitation on resources . . . . . . . . . . . . . . . 3
2.2 Usage of CMVC in such way that the extracts impact on
other users . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 Other, less likely problems . . . . . . . . . . . . . 3
2.4 Miscellaneous . . . . . . . . . . . . . . . . . . . . 3
3.0 ANALYSIS AND DIAGNOSTICS OF THE PROBLEM . . . . . . . . 5
3.1 What is the error message that is shown? . . . . . . . 5
3.2 Is the problem repeatable or intermittent? . . . . . . 5
3.3 What version of the cmvcd daemon is running? . . . . . 5
3.4 What is the target machine (the one running the NFS
server daemon)? . . . . . . . . . . . . . . . . . . . . . . 6
3.5 Is the user extracting the current or committed
versions of the release? . . . . . . . . . . . . . . . . . 6
3.6 Is the syslog daemon running? . . . . . . . . . . . . 6
3.7 Are there errors reported by the NFS server daemon on
the client? . . . . . . . . . . . . . . . . . . . . . . . . 7
3.8 Does it always fail on the same file? . . . . . . . . 7
3.9 Is there a router hop involved? . . . . . . . . . . . 7
3.10 Are the users starting/killing Release -extract
commands? . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.11 Is it possible that mount command is not in the right
location? . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.12 Is the date format correct in the family database? 8
3.13 Is CRLF conversion necessary? . . . . . . . . . . . . 9
3.14 Capturing the mount command . . . . . . . . . . . . . 9
3.15 Copying a family to recreate a problem . . . . . . 10
4.0 ADJUSTING FOR INTERMITTENT FAILURES . . . . . . . . . 11
4.1 By default, CMVC uses NFS to mount a file system . . 11
4.2 Most common failures when using NFS with OS/2 and
Windows clients . . . . . . . . . . . . . . . . . . . . . 11
4.3 Changing your system configuration . . . . . . . . . 12
Contents vii
4.3.1 Information about the NFSD and BIOD daemons . . . 12
4.3.2 CMVC_MOUNT_UNIX_PARMS and CMVC_MOUNT_OS2_PARMS . 12
4.4 What is the new function to slow down a release/level
extract? . . . . . . . . . . . . . . . . . . . . . . . . 14
4.4.1 The CMVC_EXTRACT_RELIABILITY environment variable 14
4.4.2 The CMVC_EXTRACT_SLEEP environment variable . . . 14
4.4.3 The CMVC_EXTRACT_SLEEP_FS environment variable . 15
4.5 Extracting faster, without NFS . . . . . . . . . . . 15
4.5.1 Using argument "-node NOMOUNT" . . . . . . . . . 16
4.5.2 CMVC_EXTRACT_MOUNT_NAME . . . . . . . . . . . . . 16
4.6 The final option . . . . . . . . . . . . . . . . . . 17
5.0 WHAT TO DO WHEN EVERYTHING ELSE FAILS? . . . . . . . . 19
5.1 How to use File -extract as a brute-force approach . 19
5.2 How to use the map file for committed levels to
extract files . . . . . . . . . . . . . . . . . . . . . . 20
5.3 How to recreate lost map files . . . . . . . . . . . 22
6.0 FILE EXTRACT . . . . . . . . . . . . . . . . . . . . . 25
6.1 Specifying the full path name of a CMVC file using
CMVC_TOP . . . . . . . . . . . . . . . . . . . . . . . . 25
6.1.1 Working from your current working directory . . . 26
6.1.2 Using the -relative flag . . . . . . . . . . . . 27
6.1.3 Using the CMVC_TOP variable . . . . . . . . . . . 28
6.2 Does CMVC use forward or backward slashes when
handling the file path name? . . . . . . . . . . . . . . 28
6.3 UNIX: File command adds (dot) files at extract or
check-out . . . . . . . . . . . . . . . . . . . . . . . . 29
6.4 Intel: File command adds $ to the file suffix at
extract or check-out . . . . . . . . . . . . . . . . . . 30
6.5 Restriction on file extracts into DOS or OS/2 FAT
drives . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.0 HANDLING PERFORMANCE PROBLEMS . . . . . . . . . . . . 31
7.1 Using vmstat to find performance problems . . . . . 31
7.1.1 vmstat usage . . . . . . . . . . . . . . . . . . 31
7.1.2 Interpreting the vmstat output . . . . . . . . . 32
7.1.3 Following leads provided by vmstat . . . . . . . 33
7.2 Using NetLS debugging tools that use CMVC licenses . 34
8.0 RELEASE/LEVEL/FILE -EXTRACT ERROR MESSAGES . . . . . . 35
8.1 Messages related to file system space and file
permissions . . . . . . . . . . . . . . . . . . . . . . . 35
8.2 Messages related to the format of date and time . . 38
8.3 Messages related to NFS mount and file extraction . 38
8.4 Messages related to the version control system . . . 40
9.0 INFORMATION ABOUT USING NOMOUNT . . . . . . . . . . . 43
9.1 What is the new function to avoid using NFS on
release/level extract? . . . . . . . . . . . . . . . . . 43
9.1.1 Details on the Mount option . . . . . . . . . . . 44
9.1.2 Details on the NOMOUNT option . . . . . . . . . . 44
9.1.3 Details on CMVC_NFS_DISABLE=YES option . . . . . 45
9.1.4 Implications of AFS/NIS/NIS+ . . . . . . . . . . 45
viii Solving CMVC Release -extract problems
10.0 USING CMVC WITH AFS . . . . . . . . . . . . . . . . . 47
10.1 What are the general guidelines for using CMVC with
AFS? . . . . . . . . . . . . . . . . . . . . . . . . . . 47
10.2 How to setup a CMVC family to do release extracts
into AFS space? . . . . . . . . . . . . . . . . . . . . . 48
10.3 What are some additional considerations when using
CMVC with AFS? . . . . . . . . . . . . . . . . . . . . . 49
10.4 How to solve problems with authentication when using
CMVC with AFS? . . . . . . . . . . . . . . . . . . . . . 51
10.4.1 Running fstrace to diagnose some AFS problems . 52
10.4.2 Example of results from running fstrace . . . . 53
APPENDIX A. DESCRIPTION OF TOOLS AND HOW TO GET THEM . . . 55
A.1 Description of tools . . . . . . . . . . . . . . . . 55
A.1.1 Sample mount script . . . . . . . . . . . . . . . 55
A.1.2 XFILRELC (eXtract all the FILes for a RELease,
Committed) . . . . . . . . . . . . . . . . . . . . . . . 56
A.1.3 XFILLEVU (eXtract all the FILes for a LEVel,
Uncommitted) . . . . . . . . . . . . . . . . . . . . . . 56
A.1.4 XFILLEVC (eXtract all the FILes for a LEVel,
Committed) . . . . . . . . . . . . . . . . . . . . . . . 56
A.1.5 XFILTRK (eXtract atest FILe change for all the
files in a TRacK) . . . . . . . . . . . . . . . . . . . 57
A.1.6 XFILCOMP (eXtract latest FILe change for all files
in a COMPonent) . . . . . . . . . . . . . . . . . . . . 57
A.2 Obtaining the Tools . . . . . . . . . . . . . . . . 58
A.2.1 IBM Intranet . . . . . . . . . . . . . . . . . . 58
A.2.2 Internet . . . . . . . . . . . . . . . . . . . . 58
APPENDIX B. BIBLIOGRAPHY . . . . . . . . . . . . . . . . . 61
B.1 How to get electronic copies of manuals and technical
reports . . . . . . . . . . . . . . . . . . . . . . . . . 62
B.1.1 IBM Intranet . . . . . . . . . . . . . . . . . . 62
B.1.2 Internet . . . . . . . . . . . . . . . . . . . . 62
APPENDIX C. COPYRIGHTS, TRADEMARKS AND SERVICE MARKS . . . 65
FIGURES
1. Determine the version of CMVC . . . . . . . . . . . . . 5
2. Sample script to handle map files for a manual level
extract . . . . . . . . . . . . . . . . . . . . . . . 21
Contents ix
x Solving CMVC Release -extract problems
1.0 INTRODUCTION
This technical report provides answers to frequently asked
questions made by CMVC users with respect to file, release and
level extract requests and methods of diagnosing problems.
This document is a guide for solving problems with the CMVC
Release -extract and Level -extract commands. However, these
procedures are sufficiently general to be applicable to a variety
of CMVC problems, such as performance problems. A procedure is
included for copying a family so that debugging may be performed.
Finally, a set of REXX samples is included to perform a brute-
force extract by directly using the "File -extract" command
instead of a Release/Level -extract; these tools are useful if
you do not have an NFS daemon in your Intel-based workstation.
This technical report is organized as follows:
o Overview of possible problems
o Analysis and diagnostics of the problem
o Adjusting for intermittent failures
o What to do when everything else fails
o Debugging hints
o File extract
o Handling performance problems
o Release/Level/File -extract error messages
o Details on using NOMOUNT
o Using CMVC with AFS
1.1 ABOUT THIS AND PREVIOUS TECHNICAL REPORTS
This document, as well as other recently released technical
reports related to CMVC, contains some information that was pre-
viously available in other "unofficial" documents. We have
endeavored to better organize the information and improve its
readability so that you will find it more useful.
This technical report supersedes the technical report TR 29.2130
DIAGNOSING AND SOLVING RELEASE -EXTRACT PROBLEMS WITH CMVC and it
replaces the CMVC readme file
/USR/LPP/CMVC/DOC/README.FIX.RELEASE.EXTRACT.PROBLEMS. Please
use the new technical report when possible, as we have made many
improvements and will be removing the older documents from our
shipped media and ftp sites.
For more information on normal situations on file, release and
level extracts, see the companion technical report CMVC FRE-
QUENTLY ASKED QUESTIONS: FILES, RELEASES, LEVELS AND TRACKS.
Introduction 1
1.2 ABOUT CMVC AND TEAMCONNECTION
TeamConnection is the successor product to CMVC. It has greatly
expanded capabilities and is built upon an object model. While
this and related technical reports discuss CMVC issues, we will
periodically refer to new solutions provided in TeamConnection.
Where a CMVC technical report covers a topic that might be of
importance to TeamConnection users and if the TeamConnection doc-
umentation does not already cover the topic, a TeamConnection
technical report is or will be available.
1.3 ACKNOWLEDGEMENTS
Many of the questions and answers that are compiled in this tech-
nical report were obtained from the CMVC forum in the IBMPC con-
ferencing disk and from the CMVC6000 forum in the IBMUNIX
conferencing disk.
We want to thank the main participants in these electronic forums
for their support!
Also, we want to thank Dodde Stark for editing this technical
report.
2 Solving CMVC Release -extract problems
2.0 OVERVIEW OF POSSIBLE PROBLEMS
2.1 LIMITATION ON RESOURCES
o Disk constraints; for example, using up all space in /tmp or
in the target file system.
o Memory constraints; for example, extracting the current
release which contains many files.
o Unreliable network; for example, packet timeout or the
network router is dropping packets.
2.2 USAGE OF CMVC IN SUCH WAY THAT THE EXTRACTS IMPACT ON OTHER
USERS
o Not enough daemons running; therefore, other users have to
wait to perform CMVC actions.
o Extracting -current instead of committed for large releases;
________
this option uses up too much memory and slows down the
server.
2.3 OTHER, LESS LIKELY PROBLEMS
o Using a Netware file server (older versions of CMVC cannot
change the name of read-only files).
o Writing to AFS/DFS space after the token has expired, or when
the Access Control Lists are not properly set.
o Mounting NFS file system as read-only.
o Someone has changed the ownership/permissions on the CMVC
daemon, cmvcd, which must be:
rwsr-xr-x root.system cmvcd
NOTE: On SunOS systems, the ownership is "root.root"
2.4 MISCELLANEOUS
o The NFS daemon in the client workstation is not reliable.
See 5.0, "What to do when everything else fails?" on page 19.
o The client workstation does not have an NFS daemon (such as
OS/2, Windows 95 and Windows NT). See 5.1, "How to use File
-extract as a brute-force approach" on page 19.
Overview of possible problems 3
4 Solving CMVC Release -extract problems
3.0 ANALYSIS AND DIAGNOSTICS OF THE PROBLEM
3.1 WHAT IS THE ERROR MESSAGE THAT IS SHOWN?
Is the message in the CMVC System Administration and Installation
___________________________________________
manual? We recommend using the version 2.3.
If so, then it is possible that the explanation and the action
explained in the manual could be helpful to solve the problem.
3.2 IS THE PROBLEM REPEATABLE OR INTERMITTENT?
o A repeatable problem indicates a possible file problem (for
example, a corrupted SCCS archive), or constraints of memory
and/or disk. See 7.0, "Handling performance problems" on
page 31 for details.
o Intermittent problems indicates network problems.
3.3 WHAT VERSION OF THE CMVCD DAEMON IS RUNNING?
To find out, issue the following command from the family account:
+---------------------------------------------------------------+
| |
| what `whence cmvcd` | grep cmvc |
| |
+---------------------------------------------------------------+
Figure 1. Determine the version of CMVC
NOTE: Where ` is the accent grave, in the upper left corner
in the English keyboard.
Use this command to learn the release and version of any CMVC
executable program. This is most often used for the server
daemon: cmvcd.
We have improved the handling of release and level extract in our
latest refreshes of the code.
Analysis and diagnostics of the problem 5
3.4 WHAT IS THE TARGET MACHINE (THE ONE RUNNING THE NFS SERVER
DAEMON)?
o Is it a UNIX system or something slower (such as PC)?
If using a PC, then you may need to use the new options
explained in 4.4, "What is the new function to slow down a
release/level extract?" on page 14.
o How is the file system exported?
Ensure that the CMVC server host is authorized to mount the
exported file system.
o Is the file system read-write?
Ensure that the CMVC server host can read and write into the
exported file system.
o Is the CMVC server machine authorized to perform "root" oper-
ations?
The CMVC server host needs to have this type of access in
order to write files using another user id.
3.5 IS THE USER EXTRACTING THE CURRENT OR COMMITTED VERSIONS OF
THE RELEASE?
o Extracting the current version will generate a query that can
consume significant amounts of memory.
o Extracting the committed version reads from the map file
stored in the CMVC family account, and this operation is much
faster.
3.6 IS THE SYSLOG DAEMON RUNNING?
It is highly recommended that the syslog facility be enabled and
configured properly because the syslog is the place where the
error messages from CMVC server daemon, the database and the
operating system will be stored.
To enable and configure the syslog facility see the technical
report "CMVC frequently asked questions: handling OEM platforms
and databases", section "Where are the error messages from the
CMVC daemon and databases?".
If the syslog facility is enabled, what are the error messages in
the syslog file?
If using AIX, is there any corresponding errors logged in
"errpt"?
6 Solving CMVC Release -extract problems
3.7 ARE THERE ERRORS REPORTED BY THE NFS SERVER DAEMON ON THE
CLIENT?
In OS/2 the NFS daemon runs in its own window and any errors are
displayed there.
Other operating systems can run syslog for catching network prob-
lems (for example, NFSD losing packets).
3.8 DOES IT ALWAYS FAIL ON THE SAME FILE?
If the extract always fails on the same file, is it possible to
extract the file using "File -extract"?
If the "File -extract" fails, it may be due to:
o Lack of space in /tmp or the file system of the family
account.
If the file is binary, the user needs roughly 3 times the
size of the file in /tmp.
If the file is text, the user needs roughly 2 times the size
of the file in /tmp.
o A corrupted SCCS archive. Check the archive with:
admin -h vc/../../../../s... (as specified in error message).
3.9 IS THERE A ROUTER HOP INVOLVED?
Routers can fill up and drop packets. Use a network load monitor
or the error detection tools for the router to make sure that
there is no data loss.
A slow NFS daemon (for example, the current IBM OS/2, TCP/IP
daemon) is slower than the ones on a typical UNIX system.
Try extracting locally (that is, use "-node nomount") to see if
the problem goes away. For more information on this feature,
please see 9.0, "Information about using NOMOUNT" on page 43.
Analysis and diagnostics of the problem 7
3.10 ARE THE USERS STARTING/KILLING RELEASE -EXTRACT COMMANDS?
In some cases, there are users who start a "Release -extract" and
then due to the slow performance, the users assume that the
process is hung and then kill the extract process in the CMVC
client.
When the user kills the extract on the client side, this action
does NOT kill the corresponding process on the server, which will
continue running as if nothing had happened and will terminate
when it finishes the request.
Therefore, it is possible that these users may repeat this
process of starting and killing release extracts and eventually
use up all the daemons on the server. As a result, no one else
will be able to do any work with CMVC.
Ask the system administrator to run the CMVC command "monitor" to
see how many daemons are busy running extracts; it is possible to
use "kill -1" or "kill -15" to recycle those daemons that are
doing an extract for which the user has canceled the corre-
sponding client process.
3.11 IS IT POSSIBLE THAT MOUNT COMMAND IS NOT IN THE RIGHT
LOCATION?
In some cases, like AIX 4, it is necessary to do extra configura-
tion for the "mount" command in order to be found by CMVC.
NOTE: In AIX4, the compatibility package must be installed in
order to add a symbolic link that makes mount accessible as
/etc/mount.
3.12 IS THE DATE FORMAT CORRECT IN THE FAMILY DATABASE?
The newer release of CMVC, 2.3.1 or later, uses a new date string
format (4-digit year, instead of 2-digit year format).
The family database will have to be converted to use 4-digit year
format, if you migrated from an old version CMVC to CMVC 2.3.1 or
later. Otherwise, the extract will give different results,
because the string comparisons for the date (such as, lastUpdate
date, "97/05/01" and "1997/05/01") are different.
NOTE: A tool, dbSetDate has been provided in CMVC 2.3.1 to
convert the old CMVC family databases to the new date format that
uses 4-digit year format for all dates.
8 Solving CMVC Release -extract problems
3.13 IS CRLF CONVERSION NECESSARY?
Prior to 2.3.0.22, only the OS/2 and Windows CMVC client had
support for the -crlf flag with Release/Level -extract to request
the CRLF conversion. Starting with CMVC 2.3.0.22, the -crlf flag
is now available from the UNIX CMVC line commands Release/Level.
If the files extracted have some strange characters at the end of
the line such as &caret.M and/or at the end of the file such as
&caret.Z, this indicates that CRLF (Carriage Return, Line Feed)
conversion is needed.
In general, it is necessary to request CRLF conversion (by speci-
fying -crlf at the Release/Level -extract command line) when you
want to extract release/level from an OS2 platform to a UNIX
platform.
NOTES:
1. The command with -crlf option will be slower because the con-
version has to be performed on each file in the
release/level.
2. The corresponding change in the CMVC GUI for UNIX has NOT
been made yet; that is, you cannot specify the -crlf flag
from the CMVC GUI for UNIX.
3.14 CAPTURING THE MOUNT COMMAND
In some instances, it might be necessary to deal directly with
the "mount" command to find out more details on the problem. It
is possible to capture the mount command for debugging or other
purposes:
1. Locate the directory where the mount command resides, and
change to it.
2. Rename the mount command (to be restored later).
3. Create a shell script in place of "mount".
You can take a look at the sample mentioned in the appendix
A.1.1, "Sample mount script" on page 55.
4. Call the renamed "mount" from the new mount script.
5. The script must have the same permissions as the previous
"mount" command
6. This is not a long term solution because the error handling
is not always correctly handled in a script.
Analysis and diagnostics of the problem 9
3.15 COPYING A FAMILY TO RECREATE A PROBLEM
In some extreme cases, it might be necessary to send a CMVC
family to the CMVC support team for debugging.
Refer to the technical report TR 29.22 29.2232 "How to do
migration tasks with CMVC" and to the CMVC Server Administration
__________________________
and Installation, Version 2 Release 3 manual for details on how
_____________________________________
to export a database (see Appendix C).
10 Solving CMVC Release -extract problems
4.0 ADJUSTING FOR INTERMITTENT FAILURES
We have learned from painful experience that even well managed
networks can be intermittently unreliable due to NFS. As a
result, we have provided several means of adapting the behavior
of CMVC. This chapter describes the use of NFS, some common
problems associated with this usage and some alternatives on how
to overcome these problems.
4.1 BY DEFAULT, CMVC USES NFS TO MOUNT A FILE SYSTEM
CMVC was originally designed to NFS mount a file system from the
client's workstation (running the NFS daemon), to the family
server. However, since CMVC was designed the dominant user's
workstation has changed from a UNIX workstation to a PC running a
Windows variant or OS/2.
Although NFS daemons are available for Windows and OS/2 work-
stations, these daemons have caused significant problems:
1. PC's run slower than their Unix counterparts. Even when the
operating system is not slower, the multiprocessing capabili-
ties (that is, running lots of processes through time
sharing), the device driver performance and smaller device
driver buffers impact the overall performance.
2. Extract actions to slower machines cause buffers to fill up
and overflow in routers and bridges.
3. After packets are lost, the UDP protocol used by NFS has
trouble recovering gracefully.
4.2 MOST COMMON FAILURES WHEN USING NFS WITH OS/2 AND WINDOWS
CLIENTS
NFS has a critical design weakness: it uses the UDP protocol
instead of TCP. What that means is that there is no guarantee
that a data packet will reach the intended destination intact.
Since NFS simply does not work as well on PCs, this means that
extracts to PCs fail more often. Here are the most common fail-
ures:
1. A request to create a file on the PC is received by the PC
and the file is opened, but the packet containing the file
handle is lost by the router or by the PC.
Adjusting for intermittent failures 11
After timing out, NFS resends the request to open the new
file, however, on the second try the file already exists and
the PC returns an error message that implies that the file
system is full.
2. When the CR/LF conversion occurs, there is so much
Input/Output associated with parsing and rewriting a file
(one line at a time), that packets are lost and the file
cannot be written. The problem is identified as a failure of
CR/LF conversion.
4.3 CHANGING YOUR SYSTEM CONFIGURATION
It is sometimes possible to overcome NFS problems with the
changes described below.
4.3.1 Information about the NFSD and BIOD daemons
__________________________________________________
NFSD is the daemon that handles the requests from the client
related to the file system. The BIOD daemon runs on all NFS
client systems. When a user on a client wants to read or write
to a file on a server, the BIOD daemon sends the request to the
server.
Depending on the traffic load on your system, the number of
daemons (NFSD and BIOD) can be changed. When the extract is very
slow, you may want to increase the number of daemons (See your
System Administrator for help).
4.3.2 CMVC_MOUNT_UNIX_PARMS and CMVC_MOUNT_OS2_PARMS
_____________________________________________________
It is possible to override the default NFS mount parameters for
Release/Level -extract. Many of these variable can influence the
reliability and performance of NFS during an extract.
The CMVC_MOUNT_UNIX_PARMS and CMVC_MOUNT_OS2_PARMS variables
(introduced in 2.3.0.24) override the default NFS mount parame-
ters for Release/Level -extract. By default, they are not set.
Below are some statements that can be used to specify these new
variables:
12 Solving CMVC Release -extract problems
# Change mount options when UNIX clients mount file systems
export CMVC_MOUNT_UNIX_PARMS="-o hard,intr,rw"
# Change mount options when OS/2 or Windows clients mount file systems
export CMVC_MOUNT_OS2_PARMS="-o hard,intr,rw,retry=4,timeo=14,\
retrans=6,rsize=4096,wsize=4096"
Here are the default values used by the CMVC servers; please note
that the actual value occupies one line.
HP/UX
.
CMVC_MOUNT_UNIX_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6"
CMVC_MOUNT_OS2_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6,rsize=4096,wsize=4096"
SUNOS:
CMVC_MOUNT_UNIX_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6"
CMVC_MOUNT_OS2_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6,rsize
=4096,wsize=4096"
SOLARIS:
.
CMVC_MOUNT_UNIX_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6"
CMVC_MOUNT_OS2_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6,rsize
=4096,wsize=4096"
AIX 4:
.
CMVC_MOUNT_UNIX_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6"
CMVC_MOUNT_OS2_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6,rsize
=4096,wsize=4096"
AIX 3:
.
CMVC_MOUNT_UNIX_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6"
CMVC_MOUNT_OS2_PARMS "-o
hard,intr,rw,retry=4,timeo=14,retrans=6,rsize
=4096,wsize=4096"
Adjusting for intermittent failures 13
Finally, since the above strings are compiled into cmvcd, you can
see them with a command like:
strings cmvcd | grep "hard,intr"
4.4 WHAT IS THE NEW FUNCTION TO SLOW DOWN A RELEASE/LEVEL
EXTRACT?
QUESTION:
What is the new function to slow down a release/level extract?
ANSWER:
The extract function for Release and Level has been expanded to
include an option to slow down Release/Level extracts for less
reliable networks and networks that include slow clients (such as
OS/2 and Windows workstations with slow hard disks and/or slow
processors). This function is useful in cases when packets are
lost by the NFS server daemon on workstations, bridges or
routers.
4.4.1 The CMVC_EXTRACT_RELIABILITY environment variable
________________________________________________________
The CMVC_EXTRACT_RELIABILITY environment variable can be set to
YES (yes) to indicate that you want the reliable way of doing
Release/Level extracts.
By setting CMVC_EXTRACT_RELIABILITY to NO (no), the behavior is
changed to default behavior and the following CMVC environment
variables will be ignored.
4.4.2 The CMVC_EXTRACT_SLEEP environment variable
__________________________________________________
The CMVC_EXTRACT_SLEEP environment variable is ONLY available at
the CMVC server when using CMVC_EXTRACT_RELIABILITY. It is set
to a numeric value from 0 to 2000 (in units of milliseconds).
It is important to notice that the delay specified by
CMVC_EXTRACT_SLEEP is applied at multiple points during a
Release/Level -extract.
For example, setting CMVC_EXTRACT_SLEEP=100 will result in many
1/10th second delays for each file extracted. While this can add
minutes to the total time required for a Release/Level -extract,
it also reduces the likelihood of network problems.
14 Solving CMVC Release -extract problems
4.4.3 The CMVC_EXTRACT_SLEEP_FS environment variable
_____________________________________________________
The CMVC_EXTRACT_SLEEP_FS environment variable is ONLY available
at the CMVC server when using CMVC_EXTRACT_RELIABILITY.
Often, network problems on Release/Level -extract only occur on a
select group of client workstations (such as workstations running
the CMVC client on Windows). For this reason the
CMVC_EXTRACT_SLEEP_FS environment variable can be set to the fol-
lowing values:
o DOS
This is the default. It is used for file systems designated
by drive:\path.
o UNIX
It is used for UNIX type file systems.
o ALL
It is used for all NFS mounted file systems.
If CMVC_EXTRACT_SLEEP is set, but CMVC_EXTRACT_SLEEP_FS is not
set, the default value for CMVC_EXTRACT_SLEEP_FS=DOS.
The CMVC_EXTRACT_SLEEP does not apply in the following situ-
ations:
o CMVC_EXTRACT_SLEEP is ignored when "node=nomount".
Because the NFS is not used, there is no need for the delay.
o If CMVC_EXTRACT_SLEEP=0 the delay is disabled.
4.5 EXTRACTING FASTER, WITHOUT NFS
With minor changes in your process, it is possible to avoid NFS
entirely and greatly increase the speed and reliability of your
extracts.
Adjusting for intermittent failures 15
4.5.1 Using argument "-node NOMOUNT"
_____________________________________
Release/Level -extract can specify the argument "-node NOMOUNT".
This writes the code to the family server without using NFS,
which dramatically reduces extract times.
However, you will need to transfer the files from the server to
your client! Here are some methods to accomplish it:
1. Use an alternative network file system. You can perform the
equivalent to an NFS mount by using Novell Netware, OS/2 Warp
Server, AFS, DCE/DFS, etc. prior to issuing a Release/Level
with "-extract -node NOMOUNT".
This should improve the reliability of the extract and
deliver the files to your client in one step.
2. You can extract to a file system on the server, then use a
utility such as "tar" or Info "zip" to bundle the files, send
them from the server to the client in a single step, then
unbundle the files on the client.
Since CR/LF conversion then becomes an issue, CMVC provides
the "fixcrlf" tool from the IBM software ftp site as well as
internally to IBM through the CMVC Service/Development Home
Page.
NOTES:
1. The uid/gid will be set to the client id on the server, or
the family ID if the client id is not defined.
This is the same as the default behavior for the mount
option.
2. If the users attempt to set the uid or gid, they will receive
a warning and the specified values will be ignored.
3. User must specify the attribute "-node nomount" or "-node
NOMOUNT" in order to get this optional behavior.
4. The "-root directory" must be accessible to the userid of the
client, that is, the uid/gid on the server must allow access.
4.5.2 CMVC_EXTRACT_MOUNT_NAME
______________________________
You also have the option of moving your mount point out of /tmp.
In cases where the file system is being used by many processes,
distributing the file I/O across file systems can improve per-
formance and reliability.
Starting with CMVC 2.3.0.22, it is possible to specify the tempo-
16 Solving CMVC Release -extract problems
rary directory to be used by CMVC Release or Level extracts, by
using the new CMVC environment variable:
export CMVC_EXTRACT_MOUNT_NAME=/tmp
The value of this variable is a path name for the desired tempo-
rary file directory. By default, if this variable is not speci-
fied or if the specified path name is not accessible, then /tmp
is used.
4.6 THE FINAL OPTION
In cases where NFS, or another network file system sharing mech-
anism will not work, and it is not acceptable for users to log
directly onto the family server, it is possible to do a query to
identify the files in a release and run a script to extract the
files one at a time.
Since each extract indicates success or failure, it is possible
to retry on each file and guarantee that the files are trans-
ferred. See 5.0, "What to do when everything else fails?" on
page 19 for more details.
Adjusting for intermittent failures 17
18 Solving CMVC Release -extract problems
5.0 WHAT TO DO WHEN EVERYTHING ELSE FAILS?
5.1 HOW TO USE FILE -EXTRACT AS A BRUTE-FORCE APPROACH
QUESTION:
How to use File -extract as a brute-force approach.
ANSWER:
As a workaround to Release/Level -extract problems, it is pos-
sible to extract files from a release/level without using NFS and
instead, using a brute-force approach perform a single File
-extract for each file (which does not use NFS).
This approach can also be used in situations in which the client
workstation does not have an NFS daemon (or a reliable one), such
as OS/2, Windows 95 or Windows NT. Because the tools are written
in REXX, then you may need to get REXX for Windows 95 or Windows
NT (such as Personal REXX for Windows, from Quercus Systems, P.O.
Box 2157, Saratoga, CA 95070, 408-867-REXX.
The total extraction time will be a bit longer than a pure
Release/Level extract, due to the accumulation of the small over-
head in dealing with a repeated invocation of the CMVC File
command.
The following samples (in REXX) perform the desired function:
o XFILRELC (eXtract all the FILes for a RELease, Committed).
See A.1.2, "XFILRELC (eXtract all the FILes for a RELease,
Committed)" on page 56.
This is the equivalent of doing the full extract of the
latest committed level for a release.
o XFILLEVU (eXtract all the FILes for a LEVel, Uncommitted) See
A.1.3, "XFILLEVU (eXtract all the FILes for a LEVel, Uncom-
mitted)" on page 56.
This is the equivalent of doing a delta extract of the latest
uncommitted level for a release.
The above 2 files are all that you need, but for completeness
sake we include the following supplemental samples:
What to do when everything else fails? 19
o XFILLEVC (eXtract all the FILes for a LEVel, Committed) See
A.1.4, "XFILLEVC (eXtract all the FILes for a LEVel, Com-
mitted)" on page 56.
This is the equivalent of doing a delta extract of a com-
mitted level for a release.
o XFILTRK (eXtract the latest FILe change for all the files in
a TRacK). See A.1.5, "XFILTRK (eXtract atest FILe change for
all the files in a TRacK)" on page 57.
o XFILCOMP (eXtract the latest FILe change for all the files in
a COMPonent). See A.1.6, "XFILCOMP (eXtract latest FILe
change for all files in a COMPonent)" on page 57.
5.2 HOW TO USE THE MAP FILE FOR COMMITTED LEVELS TO EXTRACT
FILES
QUESTION:
How to use the map file for committed levels to extract files.
ANSWER:
There is no single easy query that can give you all the files
that can be extracted when doing a "Level -extract -full". For
this reason, the CMVC server stores this information in map
files. There is one for each committed level for each release.
Their location is:
${FAMILY_HOME}/maps/${CMVC_RELEASE}/${LEVEL_NAME}
The format of the maps file is:
fileName versionId fileId changeType
Level -extract -full is a complicated process, but here are the
basics:
1. The list of files in a level are in
$HOME/maps/releaseName/levelName.
2. Based on the content of the map file, do the database queries
to identify which files to extract.
3. Perform File -extract -version commands to extract the file.
NOTE: If the file has been destroyed, you cannot do anything
with it.
You can experiment with the following script on the levels in
your family
20 Solving CMVC Release -extract problems
WARNING: This is a simplistic example and does not cover all
scenarios, such as destroyed files.
+---------------------------------------------------------------+
| |
| #!/usr/bin/ksh |
| |
| # The following could be made as input parameters |
| export RELEASE=r1 |
| export LEVEL=l1 |
| |
| export mapsFile=$HOME/maps/$RELEASE/$LEVEL |
| |
| while read line |
| do |
| FILENAME=`echo $line | cut -d' ' -f1 ` # field 1 i| fileName
| VERSIONID=`echo $line | cut -d' ' -f2 ` # field 2 i| version id
| FILEID=`echo $line | cut -d' ' -f3 ` # field 3 i| file id
| |
| Report -view ChangeView -where "fileId=$FILEID and \ |
| versionId=$VERSIONID and releaseName='$RELEASE' " -|aw |
| awk -F"|" '{system("/usr/lpp/cmvc/bin/File -extrac| " $5 \
| " -relative /yourAFSDir -release " $1 " -version "|$4)} '
| |
| if µ $? -ne 0 º |
| then |
| echo "This may have failed because it is a destroy|d file"
| echo "Error found in Report -view ChangeView or Fi|e -extract"
| terminate |
| fi |
| done < $mapsFile |
| |
| exit |
| |
| /* end of file */ |
| |
+---------------------------------------------------------------+
Figure 2. Sample script to handle map files for a manual level
extract
o The ChangeView will return duplicate fileName/SID combina-
tions if multiple tracks were specified upon checkin of a
file so you may need to sort the output from Report -view
ChangeView before using "awk". It is possible that the fol-
lowing will work but may not be too eloquent:
What to do when everything else fails? 21
Report -view ChangeView -where "fileId=$FILEID and \
versionId=$VERSIONID and release Name='$RELEASE' " -raw |
sed "s/\|/:/g" | sort -u -k4,5 -t: |
awk -F":" ' {system("/usr/lpp/cmvc/bin/File -extract " $5 \
" -relative /yourAFSDir -release " $1 " -version " $4)} '
o For destroyed files, the File -extract will not work since
the File entry in the database is destroyed. Therefore the
only thing you could do is issue a native SCCS command to get
the file from the CMVC server. This is NOT recommended
because it is not a good idea to allow all users to issue
native SCCS commands from the CMVC server.
TEAMCONNECTION NOTE: TeamConnection has integrated the map file
data into the database, thus allowing users direct access to the
version information for each level (Driver in TeamConnection).
5.3 HOW TO RECREATE LOST MAP FILES
QUESTION:
Some map files were deleted by mistake from the CMVC family
account. Can they be recreated manually?
ANSWER:
The map contains entries with the following format:
pathName versionId fileId type
There are easy ways to reproduce a lost map file. One possi-
bility that was proposed by the CMVC support group in Austin is:
1. You could take the map file from the previously committed
level.
2. Remove any lines with type='delete'.
3. Change the remaining types to "noDelta".
4. Get a list of the changes from the level with the lost map
file.
For each file, find the highest version (if multiple
updates).
5. Now you need the version's id and the file's id. You prob-
ably have to query the data base directly.
6. If the file is not new in the missing map file, then it has
the same id, so the query could be:
select sourceid from files where id=xxx
7. If the file is new, then the query could be:
22 Solving CMVC Release -extract problems
select id,sourceId from fileview where pathName='XXXXXXXX'
This assumes that the file has not been renamed in the mean-
time.
8. This gets the sourceId which is needed to find the version's
id:
select id from versions where sourceId=XXX and sid='X.Y'
9. If the file is new in this level, the type will be "create"
or "link".
If a file is deleted, the type is "delete".
Otherwise, the type will be "delta".
If the file was renamed, the type is "rename". This type
takes precedence over other types (by the way, the field
pathName in the map file is the new name).
Any files unchanged by the level retain the "noDelta" type.
What to do when everything else fails? 23
24 Solving CMVC Release -extract problems
6.0 FILE EXTRACT
6.1 SPECIFYING THE FULL PATH NAME OF A CMVC FILE USING CMVC_TOP
QUESTION:
Specifying the full path name of a CMVC file using CMVC_TOP
ANSWER:
The material in this section is based on Chapter 18, Part,
"TeamConnection Commands Reference".
There are a number of ways to specify the full path of a CMVC
file:
o Specify the file name (which includes the path name and base
name) and take the path from your current working directory.
o Use the "-relative" flag to specify a path name that is
outside your current working directory.
In this case, the values for the "-relative" flag and the
file name are concatenated.
o If your workstation directory structure matches the way files
are named, you can set the CMVC_TOP variable to the leading
portion of your current working directory and specify only
the base name in the actions of the "File" command.
CMVC subtracts the contents of CMVC_TOP from the current
working directory.
This option might take some time to understand, but it can
save you a great deal of typing when using line commands.
The example that follows starts with the simplest case and moves
to the more complex. Throughout the example, assume that the
environment variables for CMVC_FAMILY, CMVC_RELEASE and
CMVC_BECOME have been set.
File extract 25
6.1.1 Working from your current working directory
__________________________________________________
The main assumption for this example, is that the user is NOT
using a directory/file structure that mimics the path names of
the files stored in CMVC.
6.1.1.1 Initial checkout of txfile.c
A user is working with a file named txfile.c. The path name and
base name for this file is src/lib/txfile.c; the current working
directory on the client workstation is /robot. There is no other
file in this release named txfile.c.
1. The current working directory is: /robot
2. The user has not set CMVC_TOP yet.
3. The user enters the command:
File -checkout txfile.c
4. The family server identifies that the base name of txfile.c
is unique in the release: src/lib/txfile.c
5. The file is checked out in the workstation as:
/robot/txfile.c
6.1.1.2 Initial checkout of msg.h
Next, the user needs to check out src/lib/msg.h. Let's assume
that other files named msg.h exist in the release, thus, the user
must specify the entire path name.
1. The current working directory is: /robot
2. The user has not set CMVC_TOP yet.
3. The user enters the command:
File -checkout src/lib/msg.h
4. The family server identifies that the base name of msg.h is
not unique in the release.
5. The file is checked out in the workstation as:
/robot/src/lib/msg.h
26 Solving CMVC Release -extract problems
6.1.1.3 Miscellaneous notes
If you create a file without specifying "-relative" or setting
the CMVC_TOP variable, then a file with the same name must exist
in the current working directory. For example, you use the fol-
lowing command:
File -create src/lib/read.me
In this case, read.me must exist in your current directory; CMVC
does not search for the part in /src/lib.
6.1.2 Using the -relative flag
_______________________________
6.1.2.1 Check out again the file txfile.c from another directory
The next day, the user's current working directory is /server.
But the user wants to check out txfile.c to the /robot directory.
The user specifies the "-relative" flag to do this:
1. The current working directory is: /server
2. The user has not set CMVC_TOP yet.
3. The user enters the command:
File -checkout txfile.c -relative /robot
4. The family server identifies that the base name of txfile.c
is unique in the release: src/lib/txfile.c
5. The file is checked out in the workstation as:
/robot/src/lib/txfile.c
6.1.2.2 Check out again the file msg.h
Similar scenario, but this time with the file msg.h which is not
unique in the release, and thus, it is necessary to specify the
complete path name.
1. The current working directory is: /server
2. The user has not set CMVC_TOP yet.
3. The user enters the command:
File -checkout src/lib/msg.h -relative /robot
File extract 27
4. The family server identifies that the base name of msg.h is
not unique in the release.
5. The file is checked out in the workstation as:
/robot/src/lib/msg.h
6.1.3 Using the CMVC_TOP variable
__________________________________
A few days later, the user has checked out many files from the
release into subdirectories of /robot, using a directory struc-
ture that mimics the names of CMVC files and for convenience, the
user sets the CMVC_TOP variable to /robot.
Now when working with files, the user can specify just the base
name of the files in his current working directory, as in this
example:
1. The current working directory is: /robot/src/lib
2. The user has set CMVC_TOP to /robot
3. The user enters the command:
File -checkout txfile.c
4. The family server identifies that the base name of txfile.c
is unique in the release: src/lib/txfile.c
5. The file is checked out in the workstation as:
/robot/src/lib/txfile.c
The additional information added to the leading portion of the
path is formed by subtracting the value of CMVC_TOP from the
current working directory. In other words, the CMVC_TOP variable
tells CMVC which portion of the current working directory path
belongs to the client workstation.
This command is completely equivalent to the following command if
the CMVC_TOP variable is not set:
File -checkout src/lib/server/tx/txfile.c -relative /robot
6.2 DOES CMVC USE FORWARD OR BACKWARD SLASHES WHEN HANDLING THE
FILE PATH NAME?
QUESTION:
Does CMVC use forward or backward slashes when handling the file
path name?
28 Solving CMVC Release -extract problems
ANSWER:
The CMVC client and server will take into account the usage of
the slashes, both backward (for DOS, OS/2 and Windows) and
forward (for UNIX). The file will be treated according to the
target platform. That is, you can extract the file tmp\file.dos
into a UNIX directory and the end result will be a file in
tmp/file.dos. The reverse is also true, you can extract the file
tmp/file.aix into a DOS directory and the end result will be a
file in tmp\file.aix.
You can use the GUI to specify the relative directory to store
the code. In the UNIX GUI it is called "Set Directory", in the
OS/2 and Windows GUI is called "Relative directory" on the first
settings page.
When using the line commands the CMVC_TOP environment variable
can be used. For more details on this topic, please see page 51
in the CMVC Commands Reference, Chapter 10, Files. Actually, we
improved the explanation in the TeamConnection Commands Refer-
ence, page 98, Chapter 18, Parts (same concept).
An example of the relative directory is shown next: if the user
specifies the relative directory to C:\pages, and the file
tmp\file.dos is extracted, then the file will be located in
C:\pages\tmp\file.dos.
Another point to consider is the difference between "path name"
and "base name" when doing queries. The base name is the file
name with NO directory information, such as file.dos, while the
path name is the complete file name with the directory informa-
tion, such as tmp\file.dos.
6.3 UNIX: FILE COMMAND ADDS (DOT) FILES AT EXTRACT OR CHECK-OUT
QUESTION:
UNIX: File command adds (dot) files at extract or check-out
ANSWER:
To preserve any potential changes that users could have made to
the files on their workstation, the CMVC File command creates a
copy of a file being extracted or checked out, and this copy is
renamed with a prefix of . (dot) in order to keep it hidden
during a normal "ls" query. In order to see these dot files, you
have to issue the command "ls -a".
File extract 29
6.4 INTEL: FILE COMMAND ADDS $ TO THE FILE SUFFIX AT EXTRACT OR
CHECK-OUT
QUESTION:
File command adds $ to the file suffix at extract or check-out
when using the client for OS/2 or for Windows.
ANSWER:
To preserve any potential changes that users could have made to
the files on their workstation, the CMVC File command creates a
copy of a file being extracted or checked out, and this copy is
renamed with a suffix that begins with a $ (dollar).
6.5 RESTRICTION ON FILE EXTRACTS INTO DOS OR OS/2 FAT DRIVES
QUESTION:
Restriction on file extracts into DOS or OS/2 FAT drives
ANSWER:
Files from the CMVC server that do not conform to the 8.3 naming
convention (file name longer than 8 characters or file extensions
longer than 3 characters) cannot be extracted to a FAT drive.
30 Solving CMVC Release -extract problems
7.0 HANDLING PERFORMANCE PROBLEMS
The first step to determine whether the problem is related to the
performance of the UNIX system is to use the "vmstat" tool to
monitor system behavior. Some possible performance problems are:
o Running out of CPU cycles (becoming CPU bound)
o Running out of real memory or paging space (thrashing)
7.1 USING VMSTAT TO FIND PERFORMANCE PROBLEMS
The "vmstat" command can be used to determine both the CPU utili-
zation and the real memory availability in a UNIX system You gen-
erally run vmstat in one window, while running line commands in
another window. You can also set this up as an "at" job, redi-
recting the output to a file. The goal is to make sure you catch
the system behavior while the CMVC command and database oper-
ations are in progress.
7.1.1 vmstat usage
___________________
The vmstat command is invoked as follows:
vmstat frequency µrepetitionº
NOTES:
1. frequency is how often the system will be checked. You gen-
erally use "1", for every second.
2. repetition is optional. It is the number of times to repeat
the command. Without this parameter, vmstat will run until
the process is killed.
3. Ignore the first line of output which is an average of the
system performance from the first day the box was used.
Handling performance problems 31
7.1.2 Interpreting the vmstat output
_____________________________________
This is what to look for when running vmstat. You can find more
detailed information in the AIX commands reference or the AIX 3.2
_______
Performance Monitoring and Tuning Guide:
_______________________________________
COLUMN
heading DESCRIPTION AND POSSIBLE INTERPRETATION
AVM available memory.
If this number gets too low, processes will be swapped
out. This is one of the most expensive operations in
UNIX. The relative cost of recovering memory is shown
in paging activity and context switches.
FRE free memory list.
This is an arbitrary value, but when the number of
pages becomes too low (again, an arbitrary value), the
"initd" process runs garbage collection. This will
slow your system for a short time.
PO page out.
These operations move pages containing dormant proc-
esses to paging space. Depending on how efficiently
paging space is set up, this is either slow or very
slow. Ideally, you want paging space on several of
your least active disks (so that the least active disk
can receive the pages). Also, to improve performance
it helps to have the disks on separate SCSI controller
cards (since a single SCSI card can send data to only
one device at a time). Ideally, this number is always
0.
CS context switches.
Each context switch is a change of the active process.
It includes changing from user state to system state
when an application requests access to a privileged
device (for example, an application makes a SYSTEM()
call to write the file). The more processes you run
and the less efficiently these processes make use of
system calls, the higher this number. Ideally, this
number is at or below 100.
R process run queue.
This is the number of processes waiting for access to
the CPU. Ideally this is never greater than 1 or 2.
It is a gross indication that the system is not keeping
up with the user's demands.
32 Solving CMVC Release -extract problems
ID cpu idle.
This the amount of time that the CPU has nothing to do.
A healthy system has at least 20 percent idle. You
would probably like about 50 percent idle so that you
can handle the rough times.
WA cpu wait on device.
This number indicated the percentage of time the cpu is
waiting for a device to complete a task. If this
number is routinely high, you could have too much data
on a single disk (so lots of writes have to be serial-
ized) or have lots of delays on your network.
SY cpu system utilization.
A further indication of system problems is when "sy" is
greater then "us" (cpu user process utilization). This
is usually an indication that the system is not well
configured or that the application was written ineffi-
ciently (for example, using unbuffered write commands).
7.1.3 Following leads provided by vmstat
_________________________________________
If you see any unusual activity with vmstat, also look at the
error report log with the "errpt" command. Some of the system
problems are very visible here, for example:
o "paging space low, killing process ..."
Paging space can be checked on AIX using "lsps -a". There
should be roughly twice as much paging space as real memory
(information available from SMIT), and it should be distrib-
uted across disks.
o "token ring error ..."
Check netstat to see if there are network errors. Also, ask
the system administrator to check for the physical integrity
of the network components (such as adapter cards, cables,
etc.).
Handling performance problems 33
7.2 USING NETLS DEBUGGING TOOLS THAT USE CMVC LICENSES
In some occasions, if the NetLS configuration is not correct, the
CMVC clients may fail to execute properly because they cannot
reach the NetLS server, or they cannot obtain a valid license, or
the performance of the execution of the CMVC command may seem to
be too slow.
To help with the diagnostics and the debugging of these NetLS
configuration problems, the following executable files are pro-
vided which can be used to contact the NetLS server and request a
token for CMVC. Each program uses the same logic as a normal
CMVC line command, but it will display a lot of information that
will allow the user to better diagnose the problem with the NetLS
configuration.
Each program does not use the message catalog from CMVC, and
thus, it is an independent program. Actually, each program does
not require that CMVC should be installed at all.
The testing NetLS programs in /usr/lpp/cmvc/bin (Client code)
are:
1. test.netls.with.queues
This program uses the NetLS processing done by CMVC in 2.2,
2.3.0.0 up to 2.3.0.20.
2. test.netls.no.queues
This program uses the NetLS processing done by CMVC since
2.3.0.21, in which the previous waiting approach for NetLS
was replaced by "softstop". That is, if all the licenses for
CMVC are taken, the next user to request a license is not
placed in a queue, instead, a token is given and an entry is
added into the NetLS server log to indicate this situation.
These tools provide time stamps that can help you to determine
the overhead associated with getting a license from NetLS. If
the overhead is large (more than 1 or 2 seconds), you may have do
the procedure mentioned in the technical report "CMVC frequently
asked questions: license management with NetlS/iFOR" to optimize
the NetLS configuration.
34 Solving CMVC Release -extract problems
8.0 RELEASE/LEVEL/FILE -EXTRACT ERROR MESSAGES
The following are error messages commonly seen during
Release/Level/File -extract, and suggestions on what to do.
8.1 MESSAGES RELATED TO FILE SYSTEM SPACE AND FILE PERMISSIONS
The following two error messages indicate that the file system
runs out of space or does not have the proper file permissions.
o msgFileBadVCPut
0010-045 An error occurred when the CMVC server software tried to
check in file %1$s to the
version control file repository.
This error also occurs when a text file has some kind of
data corruption, such as an incomplete last line without EOF.
Verify that the file is complete, such as by using vi and then
saving the file to ensure that the EOF marker is added.
Also, you may try to create the file as binary instead of text.
Another possibility besides the ones mentioned in the 2nd
paragraph of the message is that the free space in /tmp is
not large enough to accommodate the actual file plus the tem-
porary copy. For more details see on page 37.
o msgErrno
0010-063 Error, %1$s, occurred when the CMVC server software attempted
to process the %2$s() function.
Usually this is a problem with fork, pipe, or other system
command. For more information see the technical report:
CMVC FREQUENTLY ASKED QUESTIONS: CMVCD, NOTIFYD,
CMVCARCHIVE/RESTORE, USER EXITS, SERVER ERRORS, DATABASE
ISSUES , section "Error message: 0010-063".
o msgExtractBadDir
0010-326 The CMVC server software cannot create directory %1$s
relative to the destination extraction directory.
Check that the parent directory permits the CMVC server soft-
ware to write to it. Also check for the existence of the
destination extraction directory and its access permissions.
If the destination extraction directory exists, ensure that
Release/Level/File -extract error messages 35
its permissions allow the CMVC server software to write to
it.
o msgErrno3
0010-350 The error (%1$s) occurred when the CMVC server software
processed function %2$s() on the file with path name %3$s.
Usually, open, read, or write, failures. Check that the path
name, the file permissions, and the directory permissions are
correct.
o msgExtractChmodFailed
0010-380 The chmod request on file %1$s
to a mode of %2$o failed during the extraction.
The file is extracted, however, the permissions cannot be
changed. Check if the server has permission to do that. You
can change the permissions manually.
o msgExtractRemoveNoWriteAccess
0010-489 The CMVC server software does not have write access to the
directory /ms/dev/releng/scmtool/1.0/src on node NOMOUNT.
Check the permissions of the exported directory, make
the necessary changes, and then retry your request.
One workaround is to use the new environment variable
CMVC_EXTRACT_MOUNT_NAME to specify a different mount point.
When the CMVC server generates this error message, another
message with more detailed information is also placed in the
syslog.
o msgExtractCannotOverwrite
0010-499 File %1$s exists in the destination
extraction directory with permissions that prevent the
CMVC server software from overwriting it.
Extract the files to an empty directory or change the access
permissions of the file or destination directory to permit
the CMVC server software to overwrite the file during the
extraction.
o msgClientNoFreeSpace
0010-677 The CMVC action was aborted while attempting to extract
file %1$s .
The file system does not have enough available space.
36 Solving CMVC Release -extract problems
o msgClientBadStatFile
0010-678 The CMVC action was aborted because the CMVC server
could not access the extracted file %1$s.
The file system does not have enough available space.
o msgErrGetPWUIDFailed
0010-802 The getpwuid() operating system subroutine failed when the
CMVC client software or the CMVC server software tried to obtain
the user's login information.
CMVC only passes the login name, not the uid from the client
to the server when doing a Release/Level -extract. There-
fore, the login name needs to be translated by the server by
using getpwuid(). If the login name is not known through
NIS, AFS or /etc/passwd, then getpwuid gets an error. Thus
far the only known problems have been when users are working
in AFS space and their token expires or their ACLs are not
set for the CMVC server to read/write the files. For more
details on AFS, see 10.0, "Using CMVC with AFS" on page 47.
o msgCrlfConvertFailed
0010-817 The CRLF conversion failed in %1$s.
There are several reasons to cause this failure:
- Cannot open temporary file (out of /tmp space).
- Cannot open the target file for write.
- The system calls fread() or fwrite() failed.
o msgFileExtractTxFailed
0010-886 An error occurred while transferring file, /blah/blah
from the CMVC server. Check your local file system.
When the CMVC server extracts a file, a temporary copy is
placed in /tmp and then this copy is transferred into the
final directory.
Thus, if this error message occurs, then either there is no
enough available space in /tmp or something is wrong with
/tmp, in which case you can try the UNIX command "fsck /tmp"
to find out the integrity of /tmp; you can use the environ-
ment variable TMPDIR to define a different directory/file
system for the location of the temporary variables.
Release/Level/File -extract error messages 37
8.2 MESSAGES RELATED TO THE FORMAT OF DATE AND TIME
The following error messages are related to the format of the
specified date. You can use "-date yy/mm/dd" to indicate that
files modified in a release/level after the specified date are to
be extracted. The date must be in the format yy/mm/dd, where
year, month, and day are two-digit character strings separated by
a slash.
o msgExtractDateBadFormat
0010-328 The format for the date, %1$s, is not valid. The date
must be in the format yy/mm/dd, where year, month, and
day are two-digit character strings separated
by a slash. For example, 91/04/28
o msgExtractDateBadMonth
0010-330 The value for month, %1$s, is not valid. The valid
range for month is 01 to 12.
o msgExtractDateBadDay
0010-331 The value for day, %1$s, is not valid. The valid
range for day is 01 to 31.
o msgExtractDateBadSubString
0010-461 The format of the date string, %1$s, is not valid.
CMVC 2.3.1 NOTE: CMVC version 2.3.1 or newer support 4-digit
year format, that is, the format of the date is, yyyy/mm/dd.
8.3 MESSAGES RELATED TO NFS MOUNT AND FILE EXTRACTION
The following messages are related to NFS mount when a real node
is specified (that is, not using "NOMOUNT"), and when files are
extracted across NFS mounted file systems. Contact the family
administrator to resolve the NFS problems.
o msgExtractVCErr
0010-025 An error occurred when the CMVC server software tried to
extract files from the version control file repository.
It could be an open file failure, a file permission problem,
and an SCCS or PVCS problem (in this case, run some SCCS or
PVCS command manually to see if it is working properly).
o msgExtractMountErr
38 Solving CMVC Release -extract problems
0010-325 The CMVC server software cannot mount directory %1$s
from node %2$s. The CMVC server software requires
mount and write access to the directory to perform
a remote extraction.
Contact your system administrator to see if the NFSD is
running and, if necessary, to manually mount/umount the
directory or to export the directory with write access.
Verify that indeed the CMVC family userid can write into that
file system.
o msgUmountBad
0010-339 The CMVC server software cannot unmount the directory %1$s
which was mounted from node %2$s.
Contact your system administrator to see if the NFSD is
running and, if necessary, to manually mount/umount the
directory or to export the directory.
o msgRemoveMountBad
0010-340 The CMVC server software cannot remove the directory %1$s.
The extraction cleanup procedure cannot be completed.
Contact your system administrator to see if the NFSD is
running and, if necessary, to manually mount/umount the
directory or to export the directory.
o msgFileNetBadTransferToClient
0010-351 An error occurred when the CMVC server software tried to open
a temporary file on the CMVC server prior to transferring
a file from the CMVC server to the CMVC client.
Check to see if the /tmp (temporary directory) is out of
space. Contact the family administrator for further problem
resolution.
o msgExtractCannotUmount
0010-492 The unmount of directory %1$s failed.
Contact your system administrator to see if the NFSD is
running and, if necessary, to manually mount/umount the
directory or to export the directory.
o msgUndefinedVCType
0010-638 The version control type, %1$s, is not valid.
Verify that the environment variable "CMVC_VCTYPE" is defined
and exported properly. SCCS and PVCS are the only supported
version control systems.
Release/Level/File -extract error messages 39
o msgExtractBadHost
0010-673 Hostname %1$s is not a known host.
Check for proper command format and that the hostname is
known to the CMVC server's nameserver.
o msgNFSDisableNoUidGid
0011-151 Warning: When CMVC_NFS_DISABLE is set to YES, or -node = NOMOUNT,
-uid and -gid values are ignored. Extract is not interrupted.
This is just a warning and does not affect the extract
process. It tells you that if you use NOMOUNT or set the
environment variable CMVC_NFS_DISABLE=YES, the gid and uid
are not used.
8.4 MESSAGES RELATED TO THE VERSION CONTROL SYSTEM
The following messages are related to your version control system
(SCCS or PVCS). For more details, see the technical report:
CMVC FREQUENTLY ASKED QUESTIONS: VERSION CONTROL AND DATABASE
SYNCHRONIZATION ISSUES.
o msgVCGetFileCannotOpen
0010-510 File %1$s could not be
retrieved. A temporary file could not be created
because the CMVC server software does not have write access.
For more details, see the technical report: CMVC FREQUENTLY
ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZA-
TION ISSUES.
o msgVCGetFailed
0010-511 An error occurred when the CMVC server software tried to
get file %1$s.
For more details, see the technical report: CMVC FREQUENTLY
ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZA-
TION ISSUES.
o msgVCGetFileDirExists
0010-595 A file and a subdirectory cannot have the same name.
File %1$s cannot be extracted.
For more details, see the technical report: CMVC FREQUENTLY
ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZA-
TION ISSUES.
40 Solving CMVC Release -extract problems
o msgVCGetFileBadWrite
0010-604 File %1$s could not be
retrieved. The CMVC server software can not create this
file on the CMVC client, %2$s.
For more details, see the technical report: CMVC FREQUENTLY
ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZA-
TION ISSUES.
o msgBinVersionInvalidSID
0011-106 An error occurred when the CMVC server software tried to
get the file %s from the version control repository.
An invalid version number was received.
For more details, see the technical report: CMVC FREQUENTLY
ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZA-
TION ISSUES.
o msgBinVersionMergeFailed
0011-107 An error occurred when the CMVC server software tried to
get the file from the version control repository. The
server failed to merge the binary files, %s and %s.
For more details, see the technical report: CMVC FREQUENTLY
ASKED QUESTIONS: VERSION CONTROL AND DATABASE SYNCHRONIZA-
TION ISSUES.
o msgBinVersionMergeMallocFailed
0011-155 binmerge could not allocate temporary memory.
It may be necessary to stop some processes or otherwise
reduce memory consumption before retrying.
o msgBinVersionMergeWriteFailed
0011-156 binmerge could not write to a temporary file.
It may be necessary to free disk space before retrying.
o msgBinVersionMergeOpenFailed
0011-157 binmerge could not open file %s.
It may be necessary to free disk space or inodes. It is also
possible that some versions of this file may be corrupted.
o msgBinVersionMergeFileCorrupt
0011-158 binmerge detected a truncated data file: %s.
Release/Level/File -extract error messages 41
It is likely that the current difference file is corrupt.
42 Solving CMVC Release -extract problems
9.0 INFORMATION ABOUT USING NOMOUNT
9.1 WHAT IS THE NEW FUNCTION TO AVOID USING NFS ON RELEASE/LEVEL
EXTRACT?
QUESTION:
What is the new function to avoid using NFS on release/level
extract?
ANSWER:
The extract function for Release and Level has been expanded to
include an option to not perform an NFS mount to extract the
files (that is, to extract to the CMVC server machine without
performing an NFS mount).
In this option the extraction will always be to a local directory
in the CMVC server host. Because if NFS is not used, then the
CMVC server will not be able to access remote directories for the
extraction.
The default function is to continue using NFS for mounting the
target directories for the extraction.
The specification for the new no-mount capability can be done as
follows:
o From the client, specify the keyword NOMOUNT as the destina-
tion host (for example, -node nomount).
For the -root attribute, specify a directory that is not
available via NFS mount. This option allows users to selec-
tively indicate which extractions will not use an NFS mount.
o From the server, set the CMVC environment variable,
CMVC_NFS_DISABLE=YES (the default is NO).
This option allows family administrators to prevent the use
of an NFS mount during extractions.
The details of the new behavior are shown in the following
sections.
Information about using NOMOUNT 43
9.1.1 Details on the Mount option
__________________________________
o If a user specifies a uid (the numeric user identification in
/etc/passwd) and/or gid (the numeric group identification in
/etc/passwd and /etc/group), all extracted files and directo-
ries will receive that uid and/or gid.
o The defaults for uid and gid are:
- If the client userid (the user name you use when logging
on, such as testclt) exists on the server, the server
will look up the uid and gid on the server and use them.
- If the id of the user exists on both the client and the
server machines, but have different uids and gids on
those machines, the extract will be done, but the userid
on the client will not own the files.
For example:
testclt on client_wsn has uid 113 and gid 14
testclt on server_wsn has uid 110 and gid 10
testfam on server_wsn has uid 115 and gid 15
The extracted files will have uid 110 and gid 10 (from
server)
- If the client userid is NOT defined on the server, then
the family uid and gid will be used (for example, uid
115, gid 15).
o File permissions filtering:
The setuid bit will always be filtered. For example:
rwsrw-rw- becomes rwxrw-rw-
rwSrw-rw- becomes rw-rw-rw-
9.1.2 Details on the NOMOUNT option
____________________________________
o Uid/gid will be set to client id on the server, or family ID
if the client id is not defined. This is the same as the
default behavior for the mount option.
o If the user attempts to set the uid or gid, they will receive
a warning, and the specified values will be ignored.
o User must specify a -node of "nomount" or "NOMOUNT" in order
to get this optional behavior.
44 Solving CMVC Release -extract problems
o The -root directory must be accessible to the userid of the
client, that is, the uid/gid on the server must allow access.
9.1.3 Details on CMVC_NFS_DISABLE=YES option
_____________________________________________
o The family administrator must define and export the
CMVC_NFS_DISABLE variable with the value either "YES" or
"yes", in the family account. This must be done before the
daemons are started.
If this variable is not specified, then the default is NO.
o Once CMVC_NFS_DISABLE is set to yes, all users will then
receive the NOMOUNT behavior:
- If the user specifies any valid -node other than
"NOMOUNT" or "nomount", they will receive a warning that
the -node is being ignored and told that their files will
be extracted to the server.
- If the "become id" (set with the -become attribute) does
not exist in the server's /etc/passwd file, the family
account id will be used for the extracted files (that is,
the family account will own the files).
If the "become id" does exist, that user id will own the
files.
- If the user account has a different uid on the server
(such as, 123 on client-a and 125 on server-b), the uid
on the server will be used (that is, 125).
9.1.4 Implications of AFS/NIS/NIS+
___________________________________
o Distributed file systems allow the user's space to be acces-
sible by the server in order to extract directly to the
server. Uid and gid must be common on all file systems.
o Some configurations of NIS+ may cause problems with userid
resolution.
o Automounting schemes may force users to do an extra step so
that their directories will be visible on the server (such as
klog in AFS).
o Automounting problems should be addressable through user
exits.
Information about using NOMOUNT 45
46 Solving CMVC Release -extract problems
10.0 USING CMVC WITH AFS
10.1 WHAT ARE THE GENERAL GUIDELINES FOR USING CMVC WITH AFS?
QUESTION:
What are the general guidelines for using CMVC with AFS?
ANSWER:
CMVC supports use of AFS space for user's files. Here are some
suggestions and limitations.
o For File -checkin, -checkout, -extract, etc., it is necessary
to have an active AFS token. CMVC will only write into AFS
space that the user is currently authorized to write.
o If a token expires it may be necessary to restart the CMVC
GUI after performing a "klog".
o Release -extract and Level -extract benefit from a new
feature in CMVC 2.3: nomount.
- Using "nomount", the user extracts into their own AFS
space on the CMVC server machine without performing an
NFS mount.
- The UID and GID of the extracted files are set to the ID
of the user on the server, therefore it is important for
each user to have the same UID and GID on all machines in
the AFS cell when using "nomount".
- Since the extraction is occurring on the server machine,
it is necessary to have an active AFS token on that
machine in order for the extract to work. This can be
accomplished with a user exit that issues the "klog"
command.
- In lieu of issuing a "klog" command, the directory where
files are to be extracted can have permissions set to
"system:anyuser all". While this is somewhat of a secu-
rity exposure, it provides for greater flexibility.
- It is possible to restrict all users to use only the
"nomount" mode for extracts, by using the following envi-
ronment variable in the .profile in the family account:
export CMVC_NFS_DISABLE=YES
Using CMVC with AFS 47
- It is important to specify the target directory cor-
rectly, especially if this command is run this from an
OS/2 client. The name of the target directory has to be
the name that the CMVC server knows and the slashes have
to be forward-slashes (as they would appear if they had
been entered on an AIX box).
o The CMVC family account should not be placed in AFS space.
There is an exposure to the reliability of CMVC if there is
any chance of an AFS token expiring while the CMVC daemons
are running.
Also, some databases cannot run in AFS space since AFS does
not support write verification.
o For additional details on using AFS with CMVC, see 10.2, "How
to setup a CMVC family to do release extracts into AFS
space?."
o For the details on how to setup a CMVC family to use AFS, see
10.3, "What are some additional considerations when using
CMVC with AFS?" on page 49.
o For the details on the usage of Release/Level -extracts with
the -nomount option, see 9.0, "Information about using
NOMOUNT" on page 43.
10.2 HOW TO SETUP A CMVC FAMILY TO DO RELEASE EXTRACTS INTO AFS
SPACE?
QUESTION:
How to setup a CMVC family to do release extracts into AFS space?
ANSWER:
Thanks to Chris Cawthorn for his feedback in this topic.
Several sites that use CMVC perform level/release extracts to AFS
without any problems.
You can only do this on versions of CMVC which allow you to
specify NOMOUNT as the node for the extract; this function was
added in CMVC 2.3.
The setup of the CMVC family is as follows:
o An AFS id is created with the same name and uid as the CMVC
family.
48 Solving CMVC Release -extract problems
o The AFS password is the same as the UNIX login password and
as the CMVC database password such as DB2_PASS or
ORACLE_PASS.
o The AFS id is given proper access in the access control list
(ACL), such as write-access to the directory that the code
will be extracted into.
o In the .profile of the CMVC family userid, the following
statement is added in order to perform klogs in to AFS:
/usr/afsws/bin/klog $CMVC_FAMILY -password $DB2_PASS
o Every night a backup job is run which performs the "su"
command to the family userid.
This job runs the .profile so the AFS token is refreshed at
least once a day.
Alternatively, you could add a user exit on the release and
level extract commands to klog in to AFS. In theory, this is
more reliable but it has not been necessary so far.
10.3 WHAT ARE SOME ADDITIONAL CONSIDERATIONS WHEN USING CMVC
WITH AFS?
QUESTION:
What are some additional considerations when using CMVC with AFS?
ANSWER:
Some additional considerations when using CMVC with AFS are shown
below:
o Prior to the extract, use a user exit to issue the "klog"
command to the CMVC server specifying the appropriate AFS
user. In order for the CMVC server to do this, either:
- The passwords for each account would need to be stored in
the family account for use with klog, or
- The CMVC server would need to be an AFS administrative
user with the authority to klog to any other user in the
group.
We have not looked into the details of implementing the above
options. However, this should work in any properly config-
ured AFS environment and should allow all files to be written
to the user's file system with the user as the owner, instead
of 32766 (AFS's anyuser id).
Using CMVC with AFS 49
o If the code from AIX /etc/login is used instead of the AFS
/etc/login code, then it is possible for the CMVC server to
"share" the AFS token with a user of the same ID on the same
workstation. In other words, if user "joe" has done klog on
the family server workstation and invokes Release -extract,
then when the CMVC daemon (cmvcd) performs a setuid to become
"joe", it would be using the same AFS token.
NOTE: The telnet command uses something other than
/etc/login, whereas the rlogin command uses /etc/login.
Therefore, use rlogin to access the family account.
o If the family account and each user are in the same AFS
authentication group, and if the group permissions are set
correctly in the user's file system, then the files will be
extracted and owned by the family account.
This is not as good as any of the options mentioned above,
but it is easier. The following command addresses the incon-
sistency with the file ownership, which is that the files are
owned by the CMVC family account and not by the desired user
(represented by xxx below):
find . -exec chown xxx {} \;
The following are some miscellaneous notes from conversations
with people from Transarc.
o If you do not use the AFS "login" command and a user issues
the "klog" command on your server, when the cmvcd daemons
later issues the function "setuid" to change the user id to
that user, then both the user and the cmvcd daemon can
"share" the token.
This is considered a security breach by Transarc, but it
might be a useful side effect when dealing with extractions.
o Make sure that all parent directories have the following
access specification:
system:anyuser rl
The directory to extract into needs to have enough authority
for cmvcd to extract file.
o Check if there are operating system issues (for example, AFS
works OK with Solaris clients, but not with SunOS ones).
o Check the permissions of any associated directories, such as
by using "ls -ld ." and "fs listacl .".
o Use the "tokens" command to see what tokens the user and the
CMVC family have on the server machine.
50 Solving CMVC Release -extract problems
o Verify that AFS and your name server are using the same ID
for the user. You can use "id user" and "pts exam user".
o Verify which version of "login" are you using:
strings `which login` | grep Base
To determine this, look for AFS in /etc/security/user and
/etc/security/login.cfg
o Verify if the version of "getty" that you are using is a sym-
bolic link to "tsm":
ls -l /etc/getty
o Verify if the cmvcd executable is in AFS space, and its file
permissions:
-rwsr-xr-x 1 root system /usr/lpp/cmvc/bin/cmvcd*
o Verify that the AFS cell is active:
fs getcellstatus -cell CELLNAME
o As user "root" you can perform the following command to find
out more about the users:
kdump -users
o Manually create a file (without the AFS tokens) and check the
file's ownership.
o Run "rxdebug <machine> 7001 -version" on a few machines.
o Perform tracing:
fs trace
10.4 HOW TO SOLVE PROBLEMS WITH AUTHENTICATION WHEN USING CMVC
WITH AFS?
QUESTION:
How to solve problems with authentication when using CMVC with
AFS?
ANSWER:
The following information was provided by Mary Ann DelBusso from
Transarc. It deals with authentication problems when using AFS
with applications such as CMVC that perform a setuid to an AFS
user and then write files into AFS space.
Using CMVC with AFS 51
The scenario is that the files that are extracted do not have the
proper file ownership and two users are involved "george" and
"wds".
o While both users (such as "george" and "wds") have tokens on
the server machine (such as "rs_aix32"), then you as user
"root" should perform the following:
kdump -users
o Then you as root should perform:
groups
o Follow the instructions in 10.4.1, "Running fstrace to diag-
nose some AFS problems" and run "fstrace" 2 times: once on a
successful run of CMVC for user "wds" and then again when
CMVC fails for user "george". Both runs should be initiated
from the same client machine. The tool "fstrace" should be
run from the CMVC server where the files are actually
written.
An example of the diagnostic results from fstrace is shown in
10.4.2, "Example of results from running fstrace" on page 53.
10.4.1 Running fstrace to diagnose some AFS problems
_____________________________________________________
There is a program called "fstrace" (documented in the AFS 3.4
release notes) which may give some more information when encount-
ering certain AFS authentication problems.
Copy "fstrace" to the local user file system (ufs) space. The
tool fstrace is normally in /usr/afsws/etc and you can copy it
into /usr/vice/etc.
Do not write the fstrace output logs to AFS space because you
need to run it from outside AFS and it should be run at a time
when no other users are accessing AFS on the machine.
Ensure that the /usr/vice/etc/C/afszcm.cat file exists and that
it is the same version of the kernel extensions running on the
client. This might be difficult to determine since the
afszcm.cat file does not have a version string associated with
it. If the file is out of date, you will see "raw" output for
some of the lines in the fstraceLog file.
The file afszcm.cat contains formatting instructions for each
type of fstrace log entry; when you run 'fstrace dump', it com-
bines the log entries with the message strings in the file to
form readable output.
52 Solving CMVC Release -extract problems
Next, you need 2 sessions on a single AFS client machine in order
to do the following (using csh):
1. In session 1, as user "root":
# Set the environment variables needed for using the afszcm.cat file
setenv NLSPATH /usr/vice/etc/%L/%N
setenv LANG C
# Do the initialization of the fstrace commands
/usr/vice/etc/fstrace clear cm
/usr/vice/etc/fstrace setlog cmfx -buffers 100
# Start the fstrace session and continuously dump the fstrace log
# to a file
/usr/vice/etc/fstrace sets cm -active
/usr/vice/etc/fstrace dump -follow cmfx -file /tmp/fstraceLog \
-sleep 10
2. In session 2:
# After starting the fstrace, you can run CMVC.
# When finished, wait a few minutes, then continue in the
# root window...
# The "fstrace dump -follow" command will not return, you need to do a
# CONTROL-C to kill it. You can also place this command in the
# background. Just make sure that you kill this when you want to stop
# the fstrace logging.
# You can run the following command to make the fstrace logging
# inactive.
/usr/vice/etc/fstrace sets cm -inactive
If you are interested in reading more about the fstrace facility,
you can check out the article that introduced it in the Cache
Update newsletter from Transarc. It was in the January 1994
edition which you can access at
/afs/transarc.com/public/afsug/newsletter/jan94
10.4.2 Example of results from running fstrace
_______________________________________________
The output from the "groups" command is shown below and it gives
a clue as to why this works for user id "wds" but not for user
"george":
Groups for george on sax3
-------------------------
33536 32533 cc7639 ccm_root
Groups for wds on sax
Using CMVC with AFS 53
---------------------------
company aplus mstk floppy idt ccm_root
The user "george" is a member of 2 groups "33536" and "32533"
while user "wds" is not a member of these groups. The two num-
bered groups mean that the AFS tokens for "george" are associated
with a PAG. Unlike "wds", it means that the tokens for "george"
are NOT shared with other processes under the same UID. For CMVC
to work, the UID-based tokens are required.
There are two ways that you could have gotten the PAG: either
you (the user id "george") is running the AFS version of login or
is specifically executing the "pagsh" command prior to running
"klog". The userid "george" needs to check .login, .cshrc,
.profile or whatever is appropriate. If the userid "george" does
not see the `pagsh` being run, then somehow, the user is getting
the AFS version of login while the user "wds" is not.
In this particular case, the userid "george" was using telnet and
the other user was using rlogin. Telnet was associated with a
PAG while rlogin was not.
54 Solving CMVC Release -extract problems
APPENDIX A. DESCRIPTION OF TOOLS AND HOW TO GET THEM
A.1 DESCRIPTION OF TOOLS
A.1.1 Sample mount script
__________________________
This sample mount script is used for debugging problems with the
behavior of the real "mount" command during the execution of the
CMVC "Release -extract" command.
NOTE: This is not to be used in a production environment. There
are some return codes that are lost due to the interaction of
this script with CMVC.
This shell script is a front end for the real /etc/mount command
that is invoked by other programs, such as the CMVC server. The
objective is to provide a way to specify different parameters
that can be tailored by the system administrator in case that the
network is busy.
See the header of the tool for the actual strings used by the
CMVC server to build the command that will invoke the mount
command. Notice that there are 2 versions of the parameters, one
for OS/2 and another for UNIX, it is necessary to identify in
this shell script which version is used.
To use this sample script, do the following:
1. Rename the real mount command to something like "/etc/mountx"
2. Save this shell script as /etc/mount
3. Edit this script to use the proper positional parameter that
is used by the CMVC server for the platform.
See the section labeled "CHANGE HERE" inside the sample
script.
Appendix A. Description of tools and how to get them 55
A.1.2 XFILRELC (eXtract all the FILes for a RELease, Committed)
________________________________________________________________
The XFILRELC tool, written in REXX, is the equivalent of doing
the full extract of the latest committed level for a release.
Syntax of tool:
USAGE: xFilRelC releaseName relativePathName
ENVIRONMENT VARIABLES:
CMVC_FAMILY
µCMVC_BECOMEº
DESCRIPTION: This sample command extracts all the files associated
with a committed release and places them in the path
specified by the relativePathName parameter.
A.1.3 XFILLEVU (eXtract all the FILes for a LEVel, Uncommitted)
________________________________________________________________
The XFILLEVU tool, written in REXX, is the equivalent of doing a
delta extract of the latest uncommitted level for a release.
Syntax of tool:
USAGE: xFilLevU releaseName levelName relativePathName
ENVIRONMENT VARIABLES:
CMVC_FAMILY
µCMVC_BECOMEº
DESCRIPTION: This sample command extracts the files associated with
an uncommitted level in the specified release
and places them in the path specified by relativePathName.
A.1.4 XFILLEVC (eXtract all the FILes for a LEVel, Committed)
______________________________________________________________
The XFILLEVC tool, written in REXX, is the equivalent of doing a
delta extract of a committed level for a release.
Syntax of tool:
USAGE: xFilLevC releaseName levelName relativePathName
ENVIRONMENT VARIABLES:
CMVC_FAMILY
µCMVC_BECOMEº
DESCRIPTION: This sample command extracts the files associated with
a committed level in the specified release
and places them in the path specified by relativePathName.
56 Solving CMVC Release -extract problems
A.1.5 XFILTRK (eXtract atest FILe change for all the files in a
________________________________________________________________
TRacK)
______
The XFILTRK tool, written in REXX, extracts all the files associ-
ated with a specific track.
Syntax of tool:
USAGE: xFilTrk releaseName trackName relativePathName
ENVIRONMENT VARIABLES:
CMVC_FAMILY
µCMVC_BECOMEº
DESCRIPTION: This sample command extracts all the files associated
with a specific track and places the files in the path
specified by relativePathName.
A.1.6 XFILCOMP (eXtract latest FILe change for all files in a
______________________________________________________________
COMPonent)
__________
The XFILCOMP tool, written in REXX, extracts all the files asso-
ciated with a specific component.
Syntax of tool:
USAGE: xFilComp componentName relativePathName µcommittedº
ENVIRONMENT VARIABLES:
CMVC_FAMILY
µCMVC_BECOMEº
DESCRIPTION: This sample command extracts all the files associated with
a specific component. The files are placed in a directory
that represents the release name to which the version of
the file is associated. This directory is created relative
to the relativePathName parameter.
Appendix A. Description of tools and how to get them 57
A.2 OBTAINING THE TOOLS
The tools described in this technical report can be downloaded as
follows:
o From the IBM intranet (only for IBM employees).
o From the Internet (open to everyone).
A.2.1 IBM Intranet
___________________
A.2.1.1 Web Home Page
You can access the CMVC Service/Development Home Page at:
http://tc-cmvc.raleigh.ibm.com/cmvc/
From the index at the top of the page, select the section
"Release extract tools".
A.2.1.2 FTP
You can download the code from our internal FTP site, by doing:
1. ftp tc-cmvc.raleigh.ibm.com
2. login as 'anonymous' and for password give your email
address.
3. cd e:/cmvc/doc/tr
4. binary
5. get fileName
6. quit
A.2.2 Internet
_______________
A.2.2.1 Web Home Page
Not available.
58 Solving CMVC Release -extract problems
A.2.2.2 FTP
You can download the code from our external FTP site, by doing:
1. ftp ftp.software.ibm.com
2. login as 'anonymous' and for password give your email
address.
3. cd ps/products/cmvc/fixes
4. binary
5. get fileName
6. quit
Appendix A. Description of tools and how to get them 59
60 Solving CMVC Release -extract problems
APPENDIX B. BIBLIOGRAPHY
For more information on how to use CMVC, you can consult the fol-
lowing manuals and publications:
SC09-1596-01 IBM CMVC Client Installation and Configuration
SC09-1597-01 IBM CMVC User's Reference
SC09-1631-02 IBM CMVC Server Administration and Installation
SC09-1633-00 IBM CMVC Concepts
SC09-1635-01 IBM CMVC Commands Reference
The following Redbooks offer practical advice on CMVC:
GG24-4178-00 Did you say CMVC?
GG24-4345 CMVC: Customer's Perspective
The following technical reports describe in detail useful hints
on using CMVC:
29.2130 Diagnosing and solving Release -extract problems with CMVC
29.2169 How to use CMVC with National Language Support (NLS)
and Double-Byte Character Sets (DBCS)
29.2180 How to do routine tasks in the OEM Platforms for CMVC
29.2183 Using CMVC for Products with Multiple
National Language Versions (NLVs)
29.2232 How to do migration tasks with CMVC
29.2244 How to build and package the CMVC client for Windows 3.1
29.2245 How to build and package the CMVC client for OS/2
29.2253 Comparison between CMVC 2.3 and TeamConnection 2
29.2254 Migrating from CMVC 2.3 to TeamConnection 2
29.2268 CMVC frequently asked questions:
license management with NetLS/iFOR
29.2269 How to build and package the CMVC Server/Client for UNIX
29.2296 CMVC frequently asked questions:
files, releases, levels, and tracks
29.2297 CMVC frequently asked questions:
version control and database synchronization issues
29.2298 CMVC frequently asked questions:
hints and tips on using databases and OEM platforms
29.2299 CMVC frequently asked questions:
client for UNIX, OS/2 and Windows 3.1
29.2321 Comparison between TeamConnection 2 and CMVC 2.3 (2nd Edition)
29.2322 CMVC/TeamConnection: How to cope with dynamic IP addresses
Appendix B. Bibliography 61
B.1 HOW TO GET ELECTRONIC COPIES OF MANUALS AND TECHNICAL
REPORTS
Many of the manuals and technical reports mentioned in this docu-
ment can be downloaded as follows:
o From the IBM intranet (only for IBM employees).
o From the Internet (open to everyone).
B.1.1 IBM Intranet
___________________
B.1.1.1 Web Home Page
You can access the CMVC Service/Development Home Page at:
http://tc-cmvc.raleigh.ibm.com/cmvc
From the index at the top of the page, select:
o Technical Reports and related tools
o Copies of ALL the archived versions for the forums CMVC and
CMVC6000
o Documentation in ASCII text files
B.1.1.2 FTP
You can download the code from our internal FTP site, by doing:
1. ftp tc-cmvc.raleigh.ibm.com
2. login as 'anonymous' and for password give your email
address.
3. cd e:\cmvc\doc\tr
4. binary
5. get fileName
6. quit
B.1.2 Internet
_______________
B.1.2.1 Web Home Page
Not available.
62 Solving CMVC Release -extract problems
B.1.2.2 FTP
You can download the code from our external FTP site, by doing:
1. ftp ftp.software.ibm.com
2. login as 'anonymous' and for password give your email
address.
3. cd ps/products/cmvc/doc
4. binary
5. get fileName
6. quit
Appendix B. Bibliography 63
64 Solving CMVC Release -extract problems
APPENDIX C. COPYRIGHTS, TRADEMARKS AND SERVICE MARKS
The following terms used in this technical report, are trademarks
or service marks of the indicated companies:
+---------------------+-------------------------------------------+
| TRADEMARK, | COMPANY |
| REGISTERED | |
| TRADEMARK OR | |
| SERVICE MARK | |
+---------------------+-------------------------------------------+
| IBM | IBM Corporation |
| AIX | |
| OS/2 | |
| CMVC | |
| TeamConnection | |
+---------------------+-------------------------------------------+
| PostScript | Adobe Systems Incorporated |
+---------------------+-------------------------------------------+
| NetLS | Gradient Technologies, Inc. |
| iForLS, iFor | |
+---------------------+-------------------------------------------+
| HP-UX | Hewlett-Packard Company |
+---------------------+-------------------------------------------+
| Info-ZIP | Info-ZIP Group |
+---------------------+-------------------------------------------+
| Intel | Intel Corp. |
+---------------------+-------------------------------------------+
| Microsoft | Microsoft Corporation |
| Windows | |
| Windows NT | |
| Windows 95 | |
| MS-DOS | |
+---------------------+-------------------------------------------+
| Novell | Novell Inc. |
| Netware | |
+---------------------+-------------------------------------------+
| Oracle | Oracle Corp. |
+---------------------+-------------------------------------------+
| OSF | Open Software Foundation, Inc. |
| DFS | |
| DCE | |
+---------------------+-------------------------------------------+
| NFS | Sun Microsystems Inc. |
| SunOS | |
| Solaris | |
+---------------------+-------------------------------------------+
| AFS | Transarc Corp. |
+---------------------+-------------------------------------------+
| UNIX | X/Open Co., Ltd. |
+---------------------+-------------------------------------------+
| Personal REXX for | Quercus Systems. |
Appendix C. Copyrights, Trademarks and Service marks 65
| Windows | |
+---------------------+-------------------------------------------+
END OF DOCUMENT
66 Solving CMVC Release -extract problems