index.html #1

<TITLE>Administering P4Web</TITLE>
<H3>
<CENTER> 
  </center>
</H3>
<p>This topic covers the following aspects of P4Web administration:
<ul>
  <li><a href="index?help#installing">Installing P4Web </a></li>
  <li><a href="index?help#start">Starting P4Web </a></li>
  <li><a href="index?help#https">Configuring P4Web with https</a></li>
  <li><a href="index?help#connecting">Connecting to P4Web</a></li>

  <li><a href="index?help#stop">Stopping P4Web</a></li>
  <li><a href="index?help#docs">P4Web documentation</a></li>
</ul>
<p>P4Web is a Perforce client program that runs on any platform. It can be used
  either in <i>Standard </i>mode or <i>Viewer </i>mode:
<ul>
  <p>
  <li><a name=standard></a><B>Standard mode</B> (default) turns your Web browser
    into a complete Perforce user interface. You can use it to work with files
    and access depot information. In Standard mode, P4Web must run on a machine
    that can read and write files in your client workspace. <br>
    <br>
    To allow other users to access your instance of P4Web, specify the <tt>-M</tt>
    flag. When multiuser access is enabled, users are required to log in and can
    choose a workspace (or can choose to browse with no workspace selected). P4Web
    displays the location of the workspace, which might reside on a remote machine.
    To work on files in remote workspaces, users download the files to their local
    machine, edit them, upload them to the machine where the workspace resides,
    then submit the files.
    <p>
  <li><a name=viewer></a><B>Viewer mode</B> allows read-only access to depot files
    and information. P4Web makes an ideal document server, enabling users to browse
    revisions 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 in Viewer mode.
</ul>
<p> To your web browser, P4Web looks like a web server. To a Perforce server,
  P4Web looks like any other Perforce client program. 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. <a name=install></a>
<h3><a name="installing"></a>Installing P4Web</h3>

<p>
P4Web is available for Macintosh, Windows, and Unix.
For download information, please go to the
<a href=	http://www.perforce.com/perforce/downloads/index.html>Perforce Downloads</a> page.

<ul>
  <p>
  <li> <b>Installing P4Web on Unix and Mac OS X</b>
    <p> Download the <b>p4web</b> 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 <kbd><B>/usr/local/bin</B></kbd> or equivalent. Make sure the
      <b>p4web</b> file has execute permission.
    <p> If you do not already have <b>p4</b> (the Perforce command line client)
      on your system, download the executable from the <a href=	http://www.perforce.com/perforce/downloads/index.html>Perforce
      Downloads</a> page and install it.
    <p>
  <li> <b>Installing P4Web on Windows</b>
    <p> Download the P4Web installer and run it on your Windows machine. When
      prompted, select <B>User</B> installation. This option installs the P4Web
      executable, <b>p4web.exe</b> and the Perforce command line client, <b>p4.exe</b>,
      if it is not already installed.
    <p>
  <li> <b>Installing P4Web as a service on Windows </b>
    <p> If you have administrative permissions, you can install P4Web to run as
      a service on your Windows machine.
    <p> Download the P4Web installer program and run it
      on your Windows workstation. If you are logged in as administrator, P4Web is installed as a service. Otherwise, the P4Web executable is installed in the directory you specify.<p> 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: <b><kbd>http://localhost:<I>P4WEBPORT</I></kbd></b>.
    <p> 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:
    <ol>
      <li><kbd>svcinst stop -n "Perforce Web"</kbd> </li>
      <li><kbd>p4 set -S "Perforce Web" P4USER=<I>username</I></kbd> </li>
      <li><kbd>svcinst start -n "Perforce Web"</kbd> </li>
    </ol>
</ul>

<p>To specify flags for P4Web services, stop the service and set  <tt>P4WEBSERVICEFLAGS</tt> as follows:</p>
<p><tt>p4 set -S &quot;Perforce Web&quot; P4WEBSERVICEFLAGS=<em>flags</em></tt></p>
<p>For example:</p>
<p> <tt>p4 set -S "Perforce Web" P4WEBSERVICEFLAGS="-M -sBCDEG"</tt></p>
<p>Then restart the service. </p>
<h3><a name=start></a> Starting P4Web </h3>
<p>When you start P4Web in Standard mode or Viewer mode, you specify the Perforce user and client that are used when P4Web connects to the Perforce server. The client view and protections defined for the specified client and user determine the scope and type of access to the Perforce server that P4Web has. For details about defining protections and client views, refer to the <em>P4 User's Guide</em>.
<h4>Starting P4Web on Windows</h4>
<p>If you installed P4Web as an application, choose <b>Start&gt;Programs&gt;Perforce&gt;Launch
  P4Web Application</b>. To specify settings other than those you configured when
  you installed P4Web, invoke it from the <a href="#cmd">command line</a>.
<p> If you are running P4Web as a service, P4Web is started immediately
  after you install it. To verify that P4Web has started, go to the <b>Windows Control
  Panel</b>. Under <b>Administrative Tools&gt;Component Services</B>, click on
  <b>Services</b> and find <b>Perforce Web</b>. If P4Web is not running, click
  <B>Start the service</B> in the left-hand column.
<h4> <a name=cmd></a>Invoking P4Web from the command line</h4>
<p> To start an instance of P4Web, invoke p4web, specifying desired options using
  the following command line flags:


<p>
<table width="90%" border="1" cellpadding="1">
  <tr>
    <td colspan="2" valign="top"><b>Command line flag</b></td>
    <td width="84%"><b>Description</b></td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-b</tt></td>
    <td width="84%">Specifies Viewer mode (no authentication). Users are not prompted
      to enter a password to connect to P4Web. However, if your user name requires
      a password when accessing Perforce, specify that password using the <tt>-P</tt>
      flag when you start P4Web. The default mode is Standard mode, in which P4Web
      can read and write files in a client workspace on the machine where P4Web
      is running. </td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-B</tt></td>
    <td width="84%">Specifies Viewer mode plus authentication. Each user is prompted
      to enter user name and password the first time they browse to the P4Web
      instance, and whenever tickets expire (if the target server is using ticket-based
      authentication). </td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-C <i>charset</i></tt></td>
    <td width="84%">Character set to be used for translation of Unicode files.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-c <i>client</i></tt></td>
    <td width="84%">Specifies the Perforce client workspace to be used to connect
      to the Perforce server. </td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-d <i>path</i></tt></td>
    <td width="84%">Specify a default file filter (for performance).</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-h </tt></td>
    <td width="84%">Displays the p4web command line flags but does not start the
      program.</td>
  </tr>
  <tr>
    <td colspan="2" height="29" valign="top"><tt>-H <i>host</i></tt></td>
    <td width="84%" height="29">Specifies the Perforce client workspace host machine.
      Because the client workspace resides on the machine where P4Web is running,
      there is typically no need to specify this flag.</td>
  </tr>

  <tr>
    <td colspan="2" height="29" valign="top"><tt>-i</tt></td>
    <td width="84%" height="29">Specify this flag in the <tt>/etc/inetd.conf</tt> file if starting P4Web using inetd.</td>
  </tr>

   <tr>
   <td colspan="2" height="29" valign="top">
      <p><tt>-In &quot;name&quot;</tt></p>
      <p><tt>-Io &quot;comment&quot;</tt></p>    </td>
    <td width="84%" height="29">Override the Perforce server's Zeroconf human-readable
      name or comment. </td>
  </tr>
  <tr>
  <tr>
    <td colspan="2" valign="top"><tt> -l </tt></td>
    <td width="84%">Accept connections only from a browser running on the local
      machine. By default, P4Web accepts connections from an authorized browser
      on any machine. (See <a href="auth?help">Passwords and Authorization</a>
      for more information.) </td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-L <i>logfilename</i></tt></td>
    <td width="84%">Log all requests sent to P4Web to the specified file. If the log file name includes spaces, specify it in double quotes.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-M</tt></td>
    <td width="84%">Accept connections from multiple users. By default, P4Web
      connects to the server and issues commands using the single user specified
      by the <tt>-u</tt> flag. When you enable connections from muliple users,
      a single instance of P4Web can interact with the Perforce server on behalf
      of all (valid) users. When users connect, they are prompted for username
      and password, and are required to choose a client workspace (if they intend
      to sync and edit files) or to select Browse mode (if they intend only to
      view information and browse files).</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-m <i>mimefilepath</i></tt></td>
    <td width="84%" valign="top">
      <p>Specify a custom MIME type map file. </p>
      <p>In the MIME type map file, you can map new types and override existing
        mappings, to control how your browser handles files returned to it by
        P4Web. As an alternative to the <tt>-m</tt> flag, you can set the <tt>P4WEBMIMEFILE</tt>
        environment variable (unless you are starting P4Web as a Windows service,
        in which case you must use the <tt>-m</tt> flag).<br>
        <br>
        The custom MIME file must be a plain text file, specifying each type mapping
        on a separate line. Each line must begin with a period, followed by the
        extension and its mapping.
      <p> <b>Example</b>:
      <blockquote>
        <p> <tt>.h text/plain<br>
          .c text/plain<br>
          .C text/plain<br>
          .cc text/plain<br>
          .cpp text/plain<br>
          .java text/plain<br>
          .pl text/plain<br>
          .py text/plain</tt></p>
      </blockquote>    </td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-p <i>host</i>:<i>port</i></tt></td>
    <td width="84%">Perforce server host and port number. Defaults to your local
      host machine and port 1666.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-P <i>password</i></tt></td>
    <td width="84%">Specifies the password for the Perforce user to be used to
      connect to the Perforce server.<b> Note:</b> This option can only be used
      in Viewer mode (<tt>-B</tt> or  <tt>-b</tt> flag).</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-r <i>path</i></tt></td>
    <td width="84%">Restrict to clients with roots in the specified path (for
      security).</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-s&nbsp;<i>options</i></tt></td>
    <td width="84%">
      <p>Specifies security-related options. Specify all options in a single instance
        of the <tt>-s</tt> flag, for example <tt>-saBD</tt>. (<b>Note:</b> <i>Remote</i>
        users are users whose browser is running on a different machine than the
        machine where P4Web is running. The <tt>-ss </tt>and <tt>-sq </tt>options
        affect both local and remote users. All other options affect only remote
        users.) Options are as follows: </p>    </td>
  </tr>
  <tr>
    <td rowspan="17" width="9%" valign="top">Options</td>
    <td width="7%"><tt>a</tt></td>
    <td width="84%">Prevent remote users from switching client workspaces.</td>
  </tr>
  <tr>
    <td width="7%"><tt>B</tt></td>
    <td width="84%">Enable remote users to use client workspaces that have no
      owner.</td>
  </tr>
  <tr>
    <td width="7%"><tt>C</tt></td>
    <td width="84%">Accept connections from any client.</td>
  </tr>
  <tr>
    <td width="7%"><tt>D</tt></td>
    <td width="84%">Enable remote users to create client workspaces. <b>Note</b>:
      by default, client workspaces created by local users are assigned a client
      root that cannot be edited. To enable local users to edit the client root,
      specify <tt>-sD</tt>.</td>
  </tr>
  <tr>
    <td width="7%"><tt>E</tt></td>
    <td width="84%">Allow remote users to edit the Root, Altroots and Owner fields
      in client workspace specifications.</td>
  </tr>
  <tr>
    <td width="7%"><tt>F</tt></td>
    <td width="84%">Enable display of startup flags for remote users.</td>
  </tr>
  <tr>
    <td width="7%"><tt>G</tt></td>
    <td width="84%">Accept connections from remote users if client has empty Host
      field. </td>
  </tr>
  <tr>
    <td width="7%"><tt>h</tt></td>
    <td width="84%">To reduce requests to the Perforce server, do not allow requests
      for integration history from server when displaying revision history, submitted
      changlelists, and jobs.</td>
  </tr>
  <tr>
    <td width="7%"><tt>i</tt></td>
    <td width="84%">Disable integration.</td>
  </tr>
  <tr>
    <td width="7%"><tt>L</tt></td>
    <td width="84%">Enable remote users to create, edit, and resolve symlinks.</td>
  </tr>
  <tr>
    <td width="7%"><tt>N</tt></td>
    <td width="84%">Enable remote users to use null-rooted client workspaces.</td>
  </tr>
  <tr>
    <td width="7%"><tt>P</tt></td>
    <td width="84%">Enable remote users to use clients that contain the recursive
      wildcard (...) in client workspace views.</td>
  </tr>
  <tr>
    <td width="7%"><tt>q</tt></td>
    <td width="84%">Disable the display of Revision History. <b>Note</b>: When
      you disable the display of Revision History, P4Web displays links to the
      file contents on the Path Browser page. This feature enables you to use
      P4Web in viewer mode as a document server. In Standard mode, you can browse
      your client workspace on the system where P4Web is running. When you are
      in Depot View, all Path Browser links take you to the depot version of the
      file. In Workspace View, all Path Browser links take you to the local version
      of the file. </td>
  </tr>
  <tr>
    <td width="7%"><tt> r</tt></td>
    <td width="84%">Disable the p4 commands feature.</td>
  </tr>
  <tr>
    <td width="7%"><tt>s</tt></td>
    <td width="84%">Generate https links instead of http links. (See <a href="#https">Configuring
      P4Web with https</a> for more information.) </td>
  </tr>
  <tr>
    <td width="7%"><tt>w</tt></td>
    <td width="84%">Suppress the display of client workspace links to files to
      remote users.</td>
  </tr>
  <tr>
    <td width="7%"><tt>x</tt></td>
    <td width="84%">Suppress the display of users' email addresses to remote users.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-T <i>tabs</i></tt></td>
    <td width="84%">Specifies the tabs to be displayed. Specify the first letter
      of the each of the desired tabs. If you omit the Files tab, the first tab
      you specify is the first tab that is displayed in your browser. The Setting
      tab cannot be hidden.
      <p> <b>Example</b>: <tt>p4web -T fps</tt> displays the Files, Pending and
        Submitted Changelist tabs.
      <p>An additional, previously hidden tab might be displayed, if it is linked
        from some other page. For example, <tt>-Tf </tt>displays the Submitted
        Changelist tab if you click a changelist number on the Revision History
        page. When you click on the Files tab, the Submitted Changelist tab is
    hidden again.    </td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-u <i>user</i> </tt></td>
    <td width="84%">Specifies the Perforce user name to be used to connect to
      the Perforce server. <b>Note:</b> This option cannot be used with the <tt>-M
      </tt> flag.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt> -U <i>username</i></tt></td>
    <td width="84%">Mandatory on UNIX systems if you start P4Web as root. For
      security purposes, P4Web drops its root privileges after binding to its
      listen address.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-V</tt></td>
    <td width="84%">Displays version information but does not start P4Web.</td>
  </tr>
  <tr>
    <td colspan="2" valign="top"><tt>-w <i>port</i></tt></td>
    <td width="84%"> 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 <tt>-w</tt> option.    </td>
  </tr>
   <tr>
    <td colspan="2" valign="top"><tt>-0</tt></td>
    <td width="84%">Register as a Zeroconf service. (Flag is zero, not the letter O). <strong>Note</strong>: the Avahi implementation of Zeroconf does not support an option for restricting the advertising of services to the localhost machine. You can prevent other machines from connecting by specifying the <tt>-l</tt> flag when you start P4Web, but if you are using Avahi, the P4Web instance is visible to other machines.</td>
  </tr>
</table>


<p>

<h3><a name="https"></a>Configuring P4Web with https</h3>

<p>To specify that all links generated in a P4Web page are https links, start
  P4Web with the <tt>-ss</tt> 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. P4Web RSS feeds also support https, if you configure stunnel
  to provide valid certificates and if your RSS reader accepts https requests.</p>
<p>For example, to set up stunnel with P4Web on Windows:
    <ol>
      <li>Download and install stunnel from <a href="http://www.stunnel.org/">http://www.stunnel.org/</a></li>
      <li>Create a text file called stunnel.p4web, containing the required configuration
        settings. For example, on Windows, enter the following settings:<br>
        &nbsp; &nbsp;<tt> [vpn]<br>
        &nbsp; &nbsp; accept = 8080<br>
        &nbsp; &nbsp; connect = 8081<br>
        &nbsp; &nbsp; TIMEOUTclose = 0</tt></li>
      <br>
      <li>Start stunnel. <b>Example</b> (full paths required):&nbsp;&nbsp;<tt>
        c:\\stunnel\\stunnel c:\\stunnel\\stunnel.p4web </tt>
      <li>Start p4web. <b>Example</b>: &nbsp;&nbsp;<tt>c:\\perforce\\p4web -w
        8081 -ss</tt>
    </ol>
    Direct your P4Web users to browse to <tt>https://<i>stunnelhost</i>:8080</tt>.
<h3><a name="connecting"></a>Connecting to P4Web</h3>
    <p> To connect to an instance of P4Web, enter the following URL in the addess
      bar of your browser:

<blockquote> <kbd><b> http://localhost:<i>nnnn</i>/&nbsp;&nbsp;&nbsp;</b></kbd>(where
  <i>nnnn</i> is the port on which p4web accepts browser requests.) </blockquote>
    The Perforce server port address is set in the environment variable <tt>P4PORT</tt>,
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 <tt>P4WEBPORT</tt>.
<p> <b>Note:</b> If your browser and P4Web are running 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).


<h3> <a name="stop"></a>Stopping P4Web</h3>
    <p> To stop a P4Web program:
    <ul>
      <p>
      <li><B>Macintosh</B>: choose <small><b>File &gt; Quit</b></small>.
        <p>
      <li><B>Windows</B>: close the P4Web console window, or type Ctrl-C in the
        window where it is running.
        <p>
      <li><B>Windows<I> </I> service</B>: to end the current session, close the
        P4Web console window. To stop the P4Web service, go to the Services console,
        find <b>Perforce Web</b> and click <b>Stop the service.</b>
        <p>
      <li><B>Unix</B>: kill the"p4web" process.
    </ul>
    <h3>Configuring the P4Web favicon</h3>
    <p>A <i>favicon</i> (short for &quot;favorites icon&quot;) is an icon associated
      with a particular website or webpage. To override P4Web's default favicon,
      either add the desired icon as <tt>//depot/favicon.ico</tt> or set <tt>P4WEBFAVICON</tt>
      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 <a href="http://www.perforce.com/perforce/doc.current/user/p4webnotes.html">P4Web
      release notes</a>.)
    <p> 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:
    <ol>
      <li>Clear the Internet Explorer cache.
      <li>Clear the cookies associated with the host where P4Web is running.
      <li>Clear history associated with that host.
      <li>Restart Internet Explorer.
      <li><b>Additional step for Internet Explorer 6:</b> 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 <b>Favorites</b> menu.
    </ol>
    <h3><a name=docs></a>User Documentation</h3>
    <p> 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:
    <P>
    <UL>
      <LI><A HREF=quickstart?help>Getting Started with Perforce and P4Web</A>
        <P>
      <LI><A HREF=roadmap?help>P4Web "Road Map"</A>
        <P>
      <LI><A HREF=auth?help>Passwords and Authorization</A>
    </UL>
</body>
</html>