Perforce Software
How to Use P4Web

How P4Web Works

P4Web is Perforce client program that runs on any platform. It can be used either in Standard mode or Viewer mode:

• Standard mode turns your Web browser into a complete Perforce user interface. You can use it to work with files and access depot information. To be used in Standard mode, P4Web must be running on a machine that can read and write files in your workspace. Typically, this is your Macintosh workstation, your Windows workstation, or the Unix machine you log in to. No one else can access your P4Web running in Standard mode -- it accepts connections from your browser only.

• Viewer mode allows read-only access to depot files and information. P4Web makes an ideal document server, allowing users to browse current and previous versions of files stored in a Perforce depot. Anyone can point their browser to P4Web instance running in Viewer mode. Perforce protections can be used to control depot access by Viewer mode if necessary.

P4Web communicates with the Perforce server using the Perforce C++ API. It also communicates with your web browser, sending HTML and receiving URL requests and form input. To your web browser, P4Web looks very much like a web server. To a Perforce server, P4Web looks like any other Perforce client program.

How to Install P4Web

P4Web is available for Macintosh, Windows, and Unix. For download information, please go to the Perforce Downloads page.

• Installing P4Web on Unix and Mac OS X

  Download the p4web executable for your Unix platform, and put it in a directory in your path. If you are installing it for everyone to use, put it in /usr/local/bin or equivalent. Make sure the p4web file has execute permission.

  If you do not already have p4 (the Perforce command line client) on your system, download the executable from the Perforce Downloads page and install it as well.

• Installing P4Web on Windows

  Download the P4Web installer program, perforce.exe, and run it on your Windows workstation. When prompted, select User installation. This installs the P4Web executable, p4web.exe. It will also install the Perforce command line client, p4.exe, if it's not already installed.

  The installer assumes you want to run P4Web on port 5501. You can override those defaults during the installation. You can also start up additional P4Webs on different port numbers regardless of the port number chosen on installation; see How to Start P4Web, below.

• Installing P4Web as a service on Windows

  If you have administrative permissions, you can install P4Web to run as a service on your Windows machine.

  Download the P4Web installer program, perforce.exe, and run it on your Windows workstation. Depending on how you want the P4Web service to run, select one of the following options:

  • Administrator Typical: runs P4Web as a service in Viewer mode.
  • Administrator Custom: allows you to choose to run P4Web in either Viewer mode or Standard mode .

  This installs the P4Web executable, p4webs.exe.

  The port number that P4Web uses when running as a service is set in the environment variable P4WEBPORT. When using P4Web as a service, point your browser to: http://localhost:value of P4WEBPORT.

  To change the user when running P4Web as a service, you must first stop the service, then set the user, then start the service again. Use the following commands to do this:

  • svcinst stop -n "Perforce Web"
  • p4 set -S "Perforce Web" P4USER=[username]
  • svcinst start -n "Perforce Web"

How to Start P4Web

Before you can point your browser to it, the P4Web program must be up and running.

On Windows, you can start the P4Web you configured during installation by clicking Start>Programs>Perforce>P4Web. You can also start a P4Web with an alternate configuration using the p4web command, as described below. Run p4web in the Start>Run window or with the p4web command in a Command Prompt window.

If you are running P4Web as a service on Windows, P4Web is already running as soon as you install it. To verify that it has started, go to the Windows Control Panel. Under Administrative Tools>Component Services, click on Services and find Perforce Web. If it is not started, click Start the service in the left-hand column.

On Mac OSX and Unix, start the P4Web program with p4web command, as described below.

The 'p4web' Command

From a command shell, run the p4web command to start a P4Web program . When P4Web starts up, it displays information about the Perforce user, client, and server port it's using, and the URL your browser should use to connect to it. The p4web command syntax is:

p4web [-w port] [-b or -B] [-l] [global_options] [-h] [-V]

• The -w port flag can be used to designate a P4Web port number other than the default. This is the port number you'll use to point your browser to P4Web.

  On Unix, the default port number is unique to each user and is displayed by the p4web command at startup. (If the default P4Web port number for your username conflicts with a port address used by another process on your system, you'll have to override it with the -w option.)

  On Windows the default P4Web port is 5051.

• The -b flag starts P4Web in the browse-only Viewer mode. This overrides the default behavior, which is to start up in Standard mode, which can read and write files in a workspace on the local machine. If the -b flag is used, you are not prompted to enter a password to connect to P4Web. However, if your username requires a password when accessing Perforce, you should also use the -P flag to enter that password when starting P4Web.

• The -B flag starts P4Web as in Viewer mode that requires authentication. The user is prompted to enter a password upon starting P4Web.

• The -l flag starts a P4Web that accepts connections only from a browser running on the local machine. Without this option, P4Web accepts connections from an authorized browser on any machine. (See Passwords and Authorization for more information.)

• [global_options] is the subset of Perforce global options supported by P4Web:

  -u user (Perforce user name) Note: This option cannot be used with the -B flag (see above).
  -P password (Perforce user password) Note: This option can only be used with the -b flag (see above).
  -c client (Perforce client name)
  -H host (Perforce client host)
  -p host:port (Perforce server host and port number)
  -C charset (Character set used for translation of unicode files)

  For more information about these flags, see the Global Options section in the Perforce Command Reference.

• The -h flag displays the p4web command flags, but does not start the program.

• The -V flag displays p4web version information, but does not start the program.

Connecting to P4Web

Once you've started a P4Web, you can connect to it with your Web browser. Point your browser to:

http://localhost:nnnn/   (where nnnn is your P4Web's port address.)

Note: If your browser is running on a different machine than P4Web, use the name of the machine P4Web is running on instead of "localhost".

Enter your Perforce username and password at your browser's prompt to begin using P4Web.

How to Stop P4Web

To stop a P4Web program running on...

• Macintosh: choose QUIT from the FILE menu.

• Windows: close the P4Web console window, or use Ctrl-C in the window it's running in.

• Windows as a service: If you simply want to end the current session, close the P4Web console window. If you want to stop the P4Web service entirely, go to the Services console, find Perforce Web and click Stop the service.

• Unix: kill your "p4web" process.

User Documentation

Once you've pointed your browser to P4Web you can use its Help links to access P4Web user documentation. You can also access the same documentation on our web site via these links:

• Getting Started with Perforce and P4Web

• P4Web "Road Map"

• Passwords and Authorization