NETWORKS.TXT: PVCS Tracker for Windows
======================================


Table of Contents
-----------------------------------------------
1. Introduction

2. Network-Specific Technical Support

3. General Network Information
3.1. Network Drivers
3.2. Network Drive Letters and Directories
3.3. Marking Files as Read-Only
3.4. Running SHARE
3.5. Network Drive Caching
3.6. File Locking
3.7. Changing Your Network Configuration
3.8. NETWORKS.WRI
3.9. True Name Support

4. PC-LAN Networks
4.1. Novell Networks
4.2. Microsoft Windows NT Advanced Server

5. Peer-to-Peer Networks
5.1. General Information
5.2. Artisoft LANtastic
5.3. Novell NetWare Lite
5.4. Microsoft Windows for Workgroups
5.5. Microsoft Windows NT

6. Unix NFS-Based Networks

7. Customizing Your Network Permissions
-----------------------------------------------



-----------------
1. Introduction
-----------------

This file contains information about installing and configuring PVCS
Tracker on various networks.

Section 2 describes our technical support policy in relationship
to network-specific problems.

Section 3, General Network Information, explains some general Tracker
configuration issues that apply to all networks.  This is a good
section to read regardless of your networking environment.

Sections 4 thru 6 give information about installing Tracker on specific
networks.

Section 7 gives information to network administrators about how
they can restrict access to Tracker files.



---------------------------------------
2. Network-Specific Technical Support
---------------------------------------

Tracker should work properly with any network that is 100% compatible with
Microsoft Windows.

In situations where Tracker is experiencing strange problems or reporting
error messages such as "TAF File Not Shareable", "File Open Error",
"File Read Error", or "File Write Error", please refer to the information
presented in this file before calling technical support.

The most common causes of such errors are insufficient network permissions,
having your networking software misconfigured, or not having the necessary
patches or service packs for your operating system installed.

It is your responsibility to correctly configure your networking software
and network permissions.  The Intersolv Technical Support Department
can provide assistance in many cases.  However, Intersolv reserves
the right to limit network-specific technical support at its discretion.



--------------------------------
3. General Network Information
--------------------------------

3.1. Network Drivers

If you are running Tracker on a network drive, be sure you have Windows
configured correctly to recognize the Tracker drive as a network drive.
This usually means you need to install and load the network drivers
for your network operating system.  Each network is different.  Please
consult your Windows documentation and network operating system
documentation.

The easiest way to check to see if your network drivers are loaded
properly is to open up the Windows File Manager and examine the drive
icon (located just underneath the tool bar).  If the drive icon looks
the same as your C: drive icon, then Windows sees the drive is a local,
non-networked drive.  Recognized network drives are indicated by a
drive icon with a network adapter symbol.

Because this is such an important aspect to Tracker running correctly,
Tracker 2.2 now checks for the presence of network drivers.  If Tracker
detects a problem, it presents you with a warning or error message.  For
more information on this message, press the Help button to view the
on-line help.  As an administrator, you can decide how Tracker should
behave when it detects a problem.  The on-line help explains this.


3.2. Network Drive Letters and Directories

You can setup Tracker to use a different drive letter or directory
than it was originally installed on.

Assuming x:\pvcstrkw is the original location, and y:\pvcstrkw is the new
location, follow these steps:

  1. With a text editor, such as Windows' NotePad, open the
     client.ini file located in Y:\PVCSTRKW\SYS.

  2. Change all references of X:\PVCSTRKW to Y:\PVCSTRKW.

  3. Save the changes.

  4. On the workstation where you wish to access Tracker, select Run ...
     from the File menu of Program Manager.

  5. As the command, enter "y:\pvcstrkw\bin\setup" to install the user
     icons only or "y:\pvcstrkw\bin\setup /Fadmin.ins" to install the
     administrative icons (do not enter the quotation marks).

  6. Follow the on-screen instructions.


3.3. Marking Files as Read-Only

The Tracker Setup program marks all executable (*.EXE and *.DLL) files as
read-only.  This is required by some networking environments to allow
simultaneous access on multiple workstations.


3.4. Running SHARE

Single workstation installations of PVCS Tracker require that
you load the DOS SHARE utility.  For convenience, we recommend you
place this in your AUTOEXEC.BAT file.

Some networks also require that you load SHARE.  If Tracker unexpectedly
reports file open errors or file not shareable errors, this could be
the cause.  Check your network vendor's documentation to determine if
SHARE is necessary.


3.5. Network Drive Caching

Because Tracker is a multi-user application, caching your network drives
can cause Tracker to behave abnormally.  In some extreme cases, this could
cause database corruption.  Although Microsoft's SmartDrive does not
allow you to cache a network drive, some network operating systems
provide their own disk caching software.  If this is the case with
your networking software, please disable network disk caching.


3.6. File Locking

Tracker requires your network to support the DOS file locking system
call (locking()) to manage multi-user database access.  Most networks
provide this.  However, on some networks it is an option that you must
enable before using Tracker.  PC/TCP, for example, supports locking, but
it is disabled by default.

If your network does not support locking, you can try setting portable=1
in the [LockConfig] section of PTKSYS.INI, but this is not guarenteed
to work.


3.7. Changing Your Network Configuration

You may change the network configuration which you originally specified
to Tracker Setup using the following procedure:

  1. Run Setup from the Tracker installation disks.

  2. Setup should recognize the existing installation and prompt
     you to update or reinstall.  Choose "Update Existing
     Installation".

  3. Setup will ask you if you wish to keep your existing network
     configuration.  Answer "No".

  4. Follow the instructions on the screen to specify a
     different network configuration.


3.8. NETWORKS.WRI

The NETWORKS.WRI file residing in your Windows directory contains
valuable information for optimally configuring your network for use
with Windows.  If you have networking problems with Tracker, you should
first follow the suggestions outlined in this file.


3.9. True Name Support

The Tracker multi-user locking mechanism maintains a file table
containing information about who is holding and awaiting file locks.
There is one entry in the file table per file in the Tracker project
database.  Entries in the file table are referenced by the file name.

Because files on a network can be referred to as different names,
depending on how you have your network drives mounted and mapped,
there is the potential for duplicate names for the same file appearing
in the file table.  For example, one user could refer to a project's
DEFECT.DAT file as K:\APPS\PVCSTRKW\DB\P1\DEFECT.DAT and another user
could refer to the same file as K:\PVCSTRKW\DB\P1\DEFECT.DAT.

To prevent this problem, Tracker converts the database file names into
their network "true name" equivalent.  The "true name" of a file is
the network device name followed by the fully qualified path of the
file.  In the above example, if K: was mapped to volume SYS1: on
server MYSERVER, then the true name equivalent of DEFECT.DAT would
be \\MYSERVER\SYS1:\APPS\PVCSTRKW\DB\P1\DEFECT.DAT.

True name conversion is an option that can be enabled or disabled.
It is enabled by default.  In some rare cases you may need to disable
true name support for your environment.  The reasons for disabling
true name support are discussed below.

True name conversion can only take place when the files reside on a
network drive.  This may not always be the case if the client
workstation you are running Tracker on is also the server that
contains the Tracker databases.  This can occur in peer-to-peer
networks or with Windows NT or Windows NT Advanced Server (NTAS).

Suppose you have two Windows for Workgroups machines, named WFW_A and
WFW_B.  Tracker is installed on the local C: drive of WFW_A.  WFW_B
mounts WFW_A's C: drive, calling it drive D:.  From WFW_B's
perspective, Tracker resides on a network drive.  However, from
WFW_A's perspective, Tracker is installed on a local drive, not a
network drive.  This configuration will confuse the file table since
WFW_A will use the non-true name for project files, while WFW_B will
use the true name equivalent.

For this reason, Tracker checks to verify that Tracker resides on a
network drive when configured for multi-user operation.  If Tracker
recognizes it is on a non-networked drive, it presents the user with
an error message.

When this occurs, the best solution is to mount the machine's own
local drive as a network drive.  Windows NT/NTAS, LANtastic, and most
other peer-to-peer networks besides Windows for Workgroups allow you
to do this.

In the case of Windows for Workgroups, you cannot mount your own local
drive as a network drive.  In this situation, the only solution is to
disable true name conversion.

To disable true name support, set truename=0 in the [LockConfig] section
of PTKSYS.INI located in \PVCSTRKW\SYS.

  [LockConfig]
  truename=0

You will also need to disable the error message that verifies Tracker is on
a network drive.  To do this, set CheckNetwork=1 in the [CheckDrivers]
section of PTKSYS.INI.

  [CheckDrivers]
  CheckNetwork=1

This turns the error message into a warning message, allowing you to
continue with the login process.  You'll also have a check box that will
disable the warning message on subsequent logins.

With true name conversion disabled, the drive letter of the files in
the file table is discarded.  This allows different workstations to
mount the Tracker drive with different drive letters.  However, you must
ensure that all users mount the drive at the same directory level.



--------------------
4. PC-LAN Networks
--------------------

4.1. Novell Networks

This section applies only to NetWare/286 or NetWare/386.  For
information on NetWare Lite, see Section 5.2.

When you install Tracker, Setup queries your Windows environment to
determine if you are accessing a Novell network.  If Setup determines
this to be the case, it will ask you if you are installing to a NetWare
file server drive.  It is important that you answer this question
correctly.  If you are simultaneously connected to multiple file
servers, and you wish to install to a non-NetWare drive, be sure to
tell Setup "No" when it asks you if you are installing to a NetWare
drive.

When Tracker installs to a NetWare drive, it installs one extra
component in your program group: DCSFLAG.BAT.  DCSFLAG.BAT is a batch
file that runs the Novell "flag" utility over all necessary Tracker
files to mark them as "shareable" in the Novell environment.  Flag is
provided with Novell NetWare.  DCSFLAG.BAT assumes that flag is
located somewhere in your path.  Setup will automatically run
DCSFLAG.BAT at the end of the installation procedure.  Also, the Add
Project Utility will run DCSFLAG.BAT to make the newly created project
shareable.

If you accidentally told Setup you were installing to a NetWare file
server, DCSFLAG.BAT will report errors to the effect of "extended drive
information not found".  These errors will not affect the operation of
Tracker.  If you would like to get rid of these errors, use the procedure
outlined in Section 3.7 above to change your network configuration.

You may wish to make changes to your Novell SHELL.CFG file.  By
default, NetWare allows you access to only 40 files at a time.  When
you are running applications with Windows, you can exceed this limit
rather quickly.  If so, you might see unexpected error messages.  To
increase the file access limit, add the following line to your
SHELL.CFG file:

   file handles = 60  (or higher)

You should also add the following to your CONFIG.SYS file:

   files = 60  (or higher)


4.2. Microsoft Windows NT Advanced Server (NTAS)

If you install Tracker on a Windows NTAS drive and are connecting to it
with Windows for Workgroups clients, then you need to install Service
Pack 2A, available from Microsoft, on the NTAS machine.

If you wish to run Tracker on the same NTAS server where Tracker is installed,
you should mount the local server drive as a network drive.  For more
details, see Section 3.9, True Name Support.



--------------------------
5. Peer-to-Peer Networks
--------------------------

5.1. General Information

PVCS Tracker can be used successfully in peer-to-peer
networking environments such as Artisoft LANtastic, Novell NetWare
Lite, Microsoft Windows for Workgroups, and others.

It is important that you correctly install your peer-to-peer software
to work properly with Microsoft Windows 3.1.  Some configuration
issues worthy of mention are:

   1) Most peer-to-peer networks require that you load
      the DOS SHARE utility, sometimes with additional
      command line parameters.

   2) Do not use SMARTDRV.EXE to write cache server drives.
      Some vendors provide their own disk caching utilities
      to use in place of SmartDrive.  You may use these to
      cache local drives that do not contain a Tracker installation.
      Do not cache your network drives.

   3) You are often required to modify settings in the Windows
      SYSTEM.INI or WIN.INI files.

Please consult your network vendor's documentation for complete details
on installing the software with Microsoft Windows.

If you wish to run Tracker on the same machine where Tracker is installed,
you should mount the local server drive as a network drive.  For more
details, see Section 3.9, True Name Support.

The following sections describe information about installing and using
PVCS Tracker with specific peer-to-peer networks.


5.2. Artisoft LANtastic

Because NetBIOS support is such an integral part of Artisoft LANtastic,
switching to the NetBIOS Lock Manager is recommended.  See Chapter 5
of the Administrator's Guide for details on how to do this.

If you wish to run Tracker on the same machine where Tracker is installed,
you should mount the local server drive as a network drive.  For more
details, see Section 3.9, True Name Support.


5.3. Novell NetWare Lite

If you are using NetWare Lite 1.0, please upgrade to NetWare Lite 1.1
or later.  Running NetWare Lite 1.0 with Microsoft Windows 3.1 is not
recommended by Novell.  Contact Novell for upgrade information.

When installing to a NetWare Lite drive, set the network configuration
to "Other Networks".  Do not specify a NetWare file server drive.

If you wish to run Tracker on the same machine where Tracker is
installed, you should mount the local server drive as a network drive.
For more details, see Section 3.9, True Name Support.


5.4. Microsoft Windows for Workgroups

If you wish to run Tracker on the same machine where Tracker is
installed, you will need to disable true name conversion.  For more
details, see Section 3.9, True Name Support.


5.5. Microsoft Windows NT

If you wish to run Tracker on the same machine where Tracker is
installed, you should mount the local server drive as a network drive.
For more details, see Section 3.9, True Name Support.



-----------------------------
6.  Unix NFS-Based Networks
-----------------------------

Tracker has been used successfully in NFS-Based networks such as Sun's PC/NFS.
This type of software allows you to mount your Unix NFS-Based drive from
your Windows workstation.

The most important aspect involved in setting up Tracker on an NFS drive
is getting your network permissions setup correctly.

Networking permissions are especially important on NFS drives because
of the way Tracker manages file locking in a multi-user environment.

In the TAF subdirectory of each project directory (e.g., \PVCSTRKW\DB\P1\TAF),
Tracker maintains files used for locking and transacation management.  There
is LOCKMGR.DBL, VISTA.TAF, and a .LOG file corresponding to each Tracker
user.  All users need to be able to read and write all of these files.

If these files do not already exist, Tracker will create them.  The
permissions assigned when the files are created causes the most problems.

When you create a file on an NFS drive, the owner id of the file is set
to your Unix user id, the group is set to your "Default Group Id", and
the permission mask is set to your "default umask".

An NFS permission mask is composed of three "read, write, execute" (rwx)
sections, one section for all users, one section for users in the file's
group, and one section for the owner of the file.  This is illustrated
below:

  rwxrwxrwx
        ---
     --- |
  --- |  +- Permissions for file owner
   |  +- Permissions for file group
   +- Permissions for all users

The umask is represented as three octal numbers, one for each section.
Each permission in a section is comprised of one bit: 1 grants the
permission, 0 denies the permission.

Example:

  r-xr-xr-x   <- Desired permission mask
  101101101   <- Binary representation
  555         <- Octal umask (101 Binary = 5 Octal)

Consult your vendor's documentation for how to set the umask.  The
easiest thing to do is set your umask to 777 to grant all users all
permissions.

If you do not want to grant everyone access to the file, you must
set your umask so that there is at least read and write access at
the group level, as shown below.

  ---rw----   <- Minimum required permission
  000110000   <- Binary representation
  060         <- Minimum required umask (110 Binary = 6 Octal)

If you decide to grant access at the group level instead of for all
users, you must then ensure that all Tracker users have a "Default
Group Id" that all Tracker users are a member of.  For example, if one
Tracker user has their Default Group Id set to Engineering, then all
users accessing Tracker must be a member of Engineering.  For
simplicity, we recommend you create a group for Tracker users, and
assign that group as the Default Group Id for all Tracker users.

The Default Group Id is specified in the Unix password file.  Consult
your system administrator or Unix documentation for more details.

Other NFS networking issues are:

  1. Ensure you have you network drivers loaded properly.  If you are
     using NFS as a secondary network (i.e., in addition to another
     network such as Novell), you made need to follow special installation
     instructions.  Consult your vendor's documentation.

  2. Do not cache network drives.  See Section 3.5.

  3. Ensure file locking is enabled.  See Section 3.6.



------------------------------------------
7.  Customizing Your Network Permissions
------------------------------------------

The easiest way to install Tracker on a network is to give all Tracker
users all permissions to Tracker files.  This is not practical in
security-conscious environments.  This section is provided to assist
network administrators in restricting access to Tracker files.

Starting with Version 2.1, we have slightly modified the directory
structure of Tracker to make it easier for network administrators to
place stricter permissions of Tracker subdirectories and files.

Each network operation system has different permission settings that
you can use.  Not all permissions are available on all networks.
Also, different terminology is used by each network operating system.

For brevity, we will use the following terms:

Our Term    Novell's Equivalent Term   Gives Permission To
--------    ------------------------   -------------------
Read        Read From File             Read contents of file
Exec        [No Equivalent]            Execute a file
Scan        File Scan                  Perform directory listing
Write       Write To File              Write to the file
Modify      Modify Directory/File      Modify file attributes
Create      Create Directory/File      Create a file or subdirectory
Erase       Erase Directory/File       Remove a file or subdirectory

Note: In some networks, Exec is equivalent to Scan.


For users of Windows NTAS file servers with an NTFS file system, the
following diagram illustrates how NTAS permissions map onto our terminology.

  Special Access (RWXD)(RWXD)
                  |||   ||||            Scan = Special Directory Access, RX
            Scan -+||   |||+- Erase
           Create -+|   ||+- Exec
              Scan -+   |+- Write
                        +- Read


Maintaining network permissions is easier if you assign permissions to
groups of users rather than individual users.  Most network operating
systems allow you to create user groups.  We recommend you create two
groups: PTKUSER, for normal Tracker users, and PTKADMIN, for Tracker
administrators.


The following tables shows the permissions needed for normal Tracker users.


Directory         Tracker Users Need             Novell         Windows NTAS
--------- -------------------------------- ---------- --------------------------
PVCSTRKW  None                             [        ]
 BIN      Read, Scan, Exec                 [ R    F ] Read (RX)(RX)
 CLONE    None                             [        ]
 DB       Scan                             [      F ] List (RX)(Not Specified)
  Pn      Read, Scan, Write, Create(*)     [ RWC  F ] Special Access (RWX)(RW)
   FILES  Read, Scan, Write, Create, Erase [ RWCE F ] Special Access (RWX)(RWD)
   TAF    Read, Scan, Write, Create, Erase [ RWCE F ] Special Access (RWX)(RWD)
 HELP     Read, Scan                       [ R    F ] Special Access (RX)(R)
 SYS      Read, Scan, Write                [ RW   F ] Special Access (RX)(RW)

* Note: You can also remove Create permissions from the project
        subdirectories (Pn).  However, you should ensure that the
        PTKPROJ.INI and PTKSTYLE.INI files exist in those directories.
        Certain Tracker operations will cause these files to be created
        if they do not exist.  Thus, the file creation will fail
        if the Create privilege is removed.

Tracker administrators need additional privileges to upgrade Tracker,
add and delete projects, etc.  For simplicity, you may want to give
Tracker administrators all access to all Tracker files.  If this is
impractical, the following tables shows the permissions needed for
Tracker administrators.


Directory     Tracker Administrators Need        Novell         Windows NTAS
--------- -------------------------------- ---------- --------------------------
PVCSTRKW  Read, Scan, Create               [ R C  F ] S.A. (RWX)(Not Specified)
 BIN      Read, Scan, Write, Modify,       [ RWCEMF ] Special Access (RWX)(RWXD)
          Create, Erase, Exec
 CLONE    Read, Scan, Write, Create, Erase [ RWC  F ] Special Access (RWX)(RWD)
 DB       Read, Scan, Modify, Create,      [ RWCEMF ] Special Access (RWX)(RWD)
          Erase
  Pn      Read, Scan, Write, Create, Erase [ RWCE F ] Special Access (RWX)(RWD)
   FILES  Read, Scan, Write, Create, Erase [ RWCE F ] Special Access (RWX)(RWD)
   TAF    Read, Scan, Write, Create, Erase [ RWCE F ] Special Access (RWX)(RWD)
 HELP     Read, Scan, Write, Create        [ RWC  F ] Special Access (RWX)(RW)
 SYS      Read, Scan, Write, Modify,       [ RWC MF ] Special Access (RWX)(RWD)
          Create

"Pn" is used to generically refer to each project subdirectory; P1, P2, etc.


Users of NFS based networks such as PC/NFS or PC/TCP should see Section 6,
"Unix NFS-Based Networks" earlier in this file for special considerations
regarding file permissions.
