Perforce 2003.2 System Administrator's Guide


<< Previous Chapter Tuning Perforce for Performance	Table of Contents Index Perforce on the Web	Next Chapter >> Perforce Proxy

Chapter 8
Perforce and Windows

This chapter describes certain information of specific interest to administrators who set up and maintain Perforce servers on Windows.


Note	Unless otherwise specified, the material presented here applies equally to Windows NT, Windows 2000, and Windows XP.

Using the Perforce installer

The Perforce installer program, perforce.exe, gives you the option to install either as a user (the Perforce client), a typical administrator (Perforce installed as a Windows service), a custom administrator (Perforce installed as a service with additional customization options), or to uninstall Perforce from your system.

If you have Administrator privileges, it is usually best to install Perforce as a service. If you don't, install it as a server.

Under Windows 2000 or higher, you need Administrator privileges to install Perforce as a service, and Power User privileges to install Perforce as a server.

Upgrade notes

The Perforce installer also automatically upgrades all types of Perforce servers (or services), even versions prior to 97.3. The upgrade process is extremely conservative; if anything fails at any step in the upgrade process, the installer stops the upgrade, and you are still able to use your old server (or service).

Installation options

When you invoke the installer, it presents an initial screen that lists the revisions of the Perforce software you're about to install. You are offered the choice between:

a user install,
a typical Administrator install,
a customized Administrator install, or
uninstalling Perforce.

User install

The "user install" installs only the Perforce Command-Line Client (p4.exe), Perforce Windows Client (P4Win), and (optionally) the third-party SCM plug-in. Under Windows 2000 or higher, this option requires Power User privileges.

You are prompted to specify the location of the client executables, the port (P4PORT) on which the client should attempt to contact the Perforce server, the default editor, and the default username.

When specifying the port for the client to use, remember to include the hostname in the form hostname:port. See "Telling Perforce client programs which port to connect to" on page 13 for more about how to set P4PORT.

If the installer detects older versions of Perforce client or server software on the machine, you are given the option to rename the old executables to prevent PATH-dependent conflicts.

Administrator typical

The "typical administrator install" allows the installation of both client and server software for Perforce. This option requires administrator privileges.

You are prompted to specify the directory for the client and server executables, the port on the local machine where the Perforce server or service will listen to client requests (P4PORT), the default editor, and the default username.

The installer selects default locations for the P4LOG error log file and the journal file. If an earlier version of Perforce was installed on the machine, these locations are based on those already in use.

If you have Administrator privileges, the installer installs Perforce and configures it to run as an auto-starting service. The service is set up and started after the installation is complete, and automatically restarts whenever the machine is rebooted. If you do not have Administrator privileges, a shortcut to run Perforce as a server is placed into your Start menu.

If the installer detects older versions of Perforce client or server software on the machine, you are given the option to rename the old executables to prevent PATH-dependent conflicts.

Administrator custom

The "custom administrator install" allows the installation of both client and server software for Perforce. This option requires administrator privileges.

As with the typical administrator install, you are prompted to specify the location of client and server executables, the port on the local machine where the Perforce server or service will listen to client requests, the default editor, and the default username.

Unlike the typical administrator install, you are allowed to optionally specify separate directories for the client and server executables, as well as server root, server port, and whether to set up Perforce as an auto-starting (or non-auto-starting) service or server process. The locations of any existing P4LOG file and journal file are displayed for reference, and may be changed later using p4 set.

If you try to install a Perforce service while another Perforce server is running, the following error message is displayed:

Setup has determined that a Perforce Server could be running. Please shut down all Perforce Servers before continuing the installation. Failure to shut down the running Perforce server(s) will result in conflicts between the newly installed service and the existing server.

As with the other installation options, if the installer detects older versions of Perforce client or server software on the machine, you are given the option to rename the old executables to prevent PATH-dependent conflicts.

Uninstalling Perforce

To remove Perforce from a Windows machine, run perforce.exe and select the Uninstall option. This option requires administrator privileges.

The uninstall procedure removes everything except your server data; the Perforce server, service, and client executables, registry keys, and service entries are all deleted. The database and depot files in your server root, however, are always preserved.

Scripted deployment and unattended installation

The Perforce installer supports scripted installation, enabling you to accelerate a deployment of Perforce across a large number of desktops.

Scripted installations are controlled by a configuration file that comes with the scriptable version of the Perforce installer. You can edit this file to preconfigure Perforce environment variables (such as P4PORT) for your environment, to automatically select Perforce client programs in use at your site, and more.

To learn more about how to automate a deployment of Perforce, see Tech Note #68 at:

http://www.perforce.com/perforce/technotes/note068.html

Perforce technical support personnel are available to answer any questions or concerns you have about automating your Perforce deployment.

Windows services vs. Windows servers

To run any task as a Windows server, a user account must be logged in, as shortcuts in a user's Startup folder cannot be run until that user logs in. A Windows service, on the other hand, is invoked automatically at boot time, and runs regardless of whether or not a user is logged in to the machine.

Throughout most of the documentation set, the terms "Perforce server" or "p4d" are used to refer to "the process at the back end that manages the database and responds to requests from Perforce clients". Under Windows, this can lead to ambiguity; the back-end process can run as either a service (p4s.exe, which runs as a thread) or as a server (p4d.exe, which runs as a regular process). From a Windows administrator's point of view, these are important distinctions. Consequently, the terminology used in this chapter uses the more precise definitions.

The Perforce service (p4s.exe) and the Perforce server (p4d.exe) executables are copies of each other; they are identical apart from their filenames. When run, they use the first three characters of the name with which they were invoked (that is, either p4s or p4d) to determine their behavior. For example, invoking copies named p4smyserver.exe or p4dmyservice.exe invokes a service and a server, respectively.

Starting and stopping the Perforce service

If Perforce was installed as a service, a user with Administrator privileges can start and stop it using the Services applet under the Control Panel.

If you are running at Release 99.2 or above, you can also use the command:

p4 admin stop to stop the Perforce service.

Starting and stopping the Perforce server

If Perforce was installed as a server, there should be a "Perforce Server" shortcut in your Start menu. To start the server, double-click on the shortcut. To stop the server, right-click on the "Perforce Server" button in the taskbar and select "Close".

You can also start the Perforce server manually from a command prompt. The server executable, p4d.exe, is normally found in your P4ROOT directory. To start the server, first make sure your current P4ROOT, P4PORT, P4LOG, and P4JOURNAL settings are correct, then run: %P4ROOT%\p4d

If you want to start a server using settings different than those set by P4ROOT, P4PORT, P4LOG, or P4JOURNAL, you can use p4d command line flags. For example:

c:\test\p4d -r c:\test -p 1999 -L c:\test\log -J c:\test\journal starts a Perforce server process with a root directory of c:\test, listening to port 1999, logging errors to c:\test\log, and with a journal file of c:\test\journal.

Note that p4d command line flags are case sensitive.

If you are running at Release 99.2 or above, use the following command:

p4 admin stop to stop the Perforce server.


Note	If you are running Release 99.1 or earlier, type Ctrl-C in the Command Prompt window, or simply Close the window. Although this method of stopping a Perforce server works in all versions of Perforce, it is not necessarily "clean". With the availability of the `p4 admin stop` command in 99.2, this method is no longer recommended.

Installing the Perforce service on a network drive

By default, the Perforce service runs under the local System account. Because the System account has no network access, a real userid and password are required in order to make the Perforce service work if the metadata and depot files are stored on a network drive.

If you are installing your server root on a network drive, the Perforce installer (perforce.exe) requests a valid combination of userid and password at the time of installation. This user must have administrator privileges. (The service, when running, will run under this user name, rather than System)

Although the Perforce service runs reliably using a network drive as the server root, there is still a marked performance penalty due to increased network traffic and slower file access. Consequently, Perforce recommends that the depot files and Perforce database reside on a drive local to the machine on which the Perforce service is running.

Multiple Perforce services under Windows

By default, the Perforce installer for Windows installs a single Perforce server as a single service. If you want to host more than one Perforce installation on the same machine (for instance, one for production and one for testing), you can either manually start Perforce servers from the command line, or use the Perforce-supplied utility svcinst.exe, to configure additional Perforce services.


Note	You must use Perforce 99.1/10994 or a later release in order to set up multiple Perforce services under Windows.


Warning	Setting up multiple services to increase the number of users you support without purchasing more user licenses is a violation of the terms of your Perforce End User License Agreement.

Understanding the precedence of environment variables in determining Perforce configuration is useful when configuring multiple Perforce services on the same machine. Before you begin, read and understand "Windows configuration parameter precedence" on page 115.

To set up a second Perforce service:

Create a new directory for the Perforce service.
Copy the server executable, service executable, and your license file into this directory.
Create the new Perforce service using the svcinst.exe utility, as described in the example below. (The svcinst.exe utility comes with the Perforce installer, and can be found in your Perforce server root.)
Set up the environment variables and start the new service.

We recommend that you install your first Perforce service using the Perforce installer. This first service is called "Perforce" and its server root directory contains files that are required by any other Perforce services you create on the machine.

Example:

Adding a second Perforce service.

You want to create a second Perforce service with a root in C:\p4root2 and a service name of "Perforce2". You are running Release 99.1/10994 or greater, and the svcinst executable is in the server root of the first Perforce installation you installed in C:\perforce.

Verify that your p4d.exe executable is at Release 99.1/10994 or greater:

p4d -V

(If you are running an older release, you must first download a more recent release from http://www.perforce.com and upgrade your server before continuing.)

Create a P4ROOT directory for the new service:

mkdir c:\p4root2

Copy the server executables - both p4d.exe (the server) and p4s.exe (the service) - and your license file into the new directory:

Use Perforce's svcinst.exe (the service installer) to create the "Perforce2" service:

svcinst create -n Perforce2 -e c:\p4root2\p4s.exe -a

After creating the "Perforce2" service, set the service parameters for the "Perforce2" service:

Finally, use the Perforce service installer to start the "Perforce2" service:

svcinst start -n Perforce2.

The second service is now running, and both services will start automatically the next time you reboot.

Windows configuration parameter precedence

Under Windows, Perforce configuration parameters can be set in many different ways. When a Perforce client program (such as p4 or P4Win), or a Perforce server program (p4d) starts up, it reads its configuration parameters according to the following precedence:

The program's command line flags have the highest precedence.
The P4CONFIG file, if P4CONFIG is set.
User environment variables.
System environment variables.
The Perforce user registry (set by p4 set).
The Perforce system registry (set by p4 set -s).

As of Release 99.1/10994, when a Perforce service (p4s) starts up, it reads its configuration parameters from the environment according to the following precedence:

Windows service parameters (set by p4 set -S servicename) have the highest precedence.
System environment variables.
The Perforce system registry (set by p4 set -s).

User environment variables can be set with any of the following:

The MS-DOS set command.
The AUTOEXEC.BAT file.
The User Variables tab under the System Properties dialog in the Control Panel.

System environment variables can be set with:

The System Variables tab under the System Properties dialog in the Control Panel.

Resolving Windows-related instabilities

There are many large sites running Perforce on Windows without incident. There are also sites in which Perforce service or server installation appears to be unstable; the server dies mysteriously, the service can't be started, and in extreme cases the system crashes. In most of these cases, this is an indication of recent changes to the machine or a corrupted operating system.

While not all Perforce failures are caused by OS-level problems, a number of symptoms may indicate the OS is at fault. Examples include: the system crashing, the Perforce server exiting without any error in its log and without Windows indicating that the server crashed, or the Perforce service not starting properly.

Perforce is supported on Windows NT 4.0 sp6a and higher, including Windows 2000 Intel x86, Windows XP Intel x86, and Windows Server 2003.

In some cases, installing third-party software after installing a Service Pack can overwrite critical files installed by the service pack; reinstalling your most-recently installed service pack can often correct these problems. If you've installed another application after your last service pack, and server stability appears affected since the installation, consider reinstalling the service pack.

As a last resort, it may pay to install Perforce on another system to see if the same failures occur, or even to reinstall the OS and Perforce on the faulty system.

Users having trouble with P4EDITOR or P4DIFF

Your Windows users may experience difficulties using the Perforce Command-Line Client (p4.exe) if they use the P4EDITOR or P4DIFF environment variables.

The reason for this is that Perforce clients sometimes use the DOS shell (cmd.exe) to start programs such as user-specified editors or diff utilities. Unfortunately, the DOS shell knows that when a Windows command is run (such as a GUI-based editor like notepad.exe), the shell doesn't have to wait for the command to complete before terminating. When this happens, the Perforce client then mistakenly believes that the command has finished, and attempts to continue processing, often deleting the temporary files that the editor or diff utility had been using, leading to error messages about temporary files not being found, or other strange behavior.

You can get around this problem in two ways:

Unset the environment variable SHELL. Perforce clients under Windows only use cmd.exe when SHELL is set, otherwise they call spawn() and wait for the Windows programs to complete.
Set the P4EDITOR or P4DIFF variable to the name of a batch file whose contents are the command:

where program is the name of the editor or diff utility you wish to invoke. The /wait flag instructs the system to wait for the editor or diff utility to terminate, enabling the Perforce client program to behave properly.

Some Windows editors (most notably, Wordpad) do not exhibit proper behavior, even when instructed to wait. There is presently no workaround for such programs.