P4Web User Guide - Administering P4Web

P4Web Release 2007.2 User Guide
[Getting Started] [How To...] [Browser Tips] [Glossary] [Road Map]

Administering P4Web

This topic covers the following aspects of P4Web administration:

P4Web is a 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 only from your browser.
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 like a web server. To a Perforce server, P4Web looks like any other Perforce client program.

Installing 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.
Installing P4Web on Windows
Download the P4Web installer program, perforce.exe, and run it on your Windows workstation. When prompted, select User installation. This option installs the P4Web executable, p4web.exe and the Perforce command line client, p4.exe, if it is not already installed.
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. When prompted, select one of the following options:
- Administrator Typical: runs P4Web as a service in Viewer mode.
- Administrator Custom: enables you to run P4Web in either Viewer mode or Standard mode .
This option installs the P4Web executable, p4webs.exe.
The port number that P4Web uses when running as a service is specified by setting the environment variable P4WEBPORT. When using P4Web as a service, point your browser to: http://localhost: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. At the DOS prompt, issue the following commands:
1. svcinst stop -n "Perforce Web"
2. p4 set -S "Perforce Web" P4USER=username
3. svcinst start -n "Perforce Web"

Starting P4Web

There are two ways to start P4Web: on Windows as a service, or on all supported platforms from the command line.

Starting the Windows service

On Windows, you can start the P4Web you configured during installation by choosing 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 by issuing the p4web command at the DOS prompt.

If you are running P4Web as a service on Windows, P4Web is started immediately after 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 P4Web is not started, click Start the service in the left-hand column.

Invoking from the command line

To start an instance of P4Web, issue the p4web command. The p4web command syntax is as follows:

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

-w port: specifies the port on which P4Web accepts browser requests.
On Windows and Macintosh, the default port for P4Web is 8080. On UNIX and related platforms, the port used by P4Web is the 5000 plus the P4Web user's UID. For example, if the user's UID is 525, then, by default, P4Web uses port 5525. You can start multiple instances of P4Web using on different port numbers regardless of the port number chosen during installation. To override the default port, specify another port using the -w option.
-b: specifies Viewer mode. The default mode is Standard mode, in which P4Web 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, specify that password using the -P flag when you start P4Web.
-B: require authentication. You are prompted to enter a password upon starting P4Web.
-ss: generate https links instead of http links. (See Configuring P4Web with https for more information.)
-l: accept connections only from a browser running on the local machine. By default, P4Web accepts connections from an authorized browser on any machine. (See Passwords and Authorization for more information.)
-L logfilename: log all requests sent to P4Web.

[global_options] are as follows:
-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 Perforce Command Reference.

Other flags:

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.

When P4Web starts, it displays the Perforce user, client, and server port it is using, and the URL to be used by browsers to connect to the instance.

Configuring P4Web with https

To specify that all links generated in a P4Web page are https links, start P4Web with the -ss flag. Note that P4Web does not accept https requests. To convert https requests to http so P4Web can process them, use an https converter such as stunnel.

For example, to set up stunnel with P4Web on Windows:

Download and install stunnel from http://www.stunnel.org/
Create a text file called stunnel.p4web, containing the required configuration settings. For example, on Windows, enter the following settings:
[vpn] accept = 8080 connect = 8081 TIMEOUTclose = 0

Start stunnel. Example (full paths required): c:\\stunnel\\stunnel c:\\stunnel\\stunnel.p4web
Start p4web. Example: c:\\perforce\\p4web -w 8081 -ss

Direct your P4Web users to browse to https://stunnelhost:8080.

P4Web RSS feeds also support https, if you configure stunnel to provide valid certificates and if your RSS reader accepts https requests.

Configuring the P4Web favicon

A favicon (short for "favorites icon") is an icon associated with a particular website or webpage. To override P4Web's default favicon, either add the desired icon as //depot/favicon.ico or set P4WEBFAVICON to the depot path of the desired icon file in your depot. The favicon is served to Firefox and Safari browsers, and to Opera browsers unless the user was logged into the browser session using a cookie. (Opera fails to serve the cookie when it requests /favicon.ico so the internal version will be served instead. For details about why P4Web uses cookies to log users in, see the P4Web release notes.)

To enable Internet Explorer to display the P4Web favicon, you must be running version 6 or higher. To display the icon, your users must perform the following steps:

Clear the Internet Explorer cache.
Clear the cookies associated with the host where P4Web is running.
Clear history associated with that host.
Restart Internet Explorer.
Additional step for Internet Explorer 6: Add the page to your favorites. If you already have the page in your favorites folder, remove it and add it again. The favicon is displayed in the URL field when you open the page using the Favorites menu.

Connecting to P4Web

To connect to an instance of P4Web, enter the following URL in the addess bar of your browser:

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

The port address is set in the environment variable P4PORT, unless you are running P4Web as a service on Windows. If you are running P4Web as a service, the port address is set in the environment variable P4WEBPORT.

Note: If your browser and P4Web are runing on different machines, specify the name of the machine where P4Web is running instead of "localhost".

When prompted, enter your Perforce username and password (if any).

Stopping P4Web

To stop a P4Web program:

Macintosh: choose File > Quit.
Windows: close the P4Web console window, or type Ctrl-C in the window where it is running.
Windows service: to end the current session, close the P4Web console window. To stop the P4Web service, go to the Services console, find Perforce Web and click Stop the service.
Unix: kill the"p4web" process.

User Documentation

After you've pointed your browser to P4Web, use its online help to view the user documentation. You can also access the online help from the Perforce web site, as follows: