Chapter 1
Installing and Configuring P4FTP

This chapter tells system administrators how to install and configure P4FTP.

System requirements

• FTP client: a command-line client or a web authoring tool such as Dreamweaver, which has an FTP client embedded in it. The FTP client communicates with P4FTP.

• P4FTP: accepts requests from an FTP client and communicates with a Perforce server.

• Perforce server: manages files in central repositories called depots. (Note: if you use versions lower than 2000.2, P4FTP does not display files size when you issue the FTP ls command.)

• Perforce client application: enables you to perform Perforce tasks directly. The most commonly-used Perforce client applications are P4V, the P4 command-line interface, and P4Web.

The following table shows you where the components are installed. Note that you can install two or more components on the same computer. However, the Perforce server is typically a remote computer, because there is no advantage to be gained by locating your depot on the same computer as the workspace files.

Product architecture

There are some important differences in behavior between P4FTP and a normal FTP server. For details about these differences, refer to Chapter 3, Perforce and FTP Differences.

Installation and configuration

1. Download P4FTP.

2. Choose a port number.

3. Start P4FTP.

4. Optionally, configure P4FTP to start automatically when you reboot the computer on which it runs.

5. Create Perforce users and workspace specifications.

Downloading P4FTP

1. Launch a web browser and go to:

   http://www.perforce.com/perforce/products/p4ftp.html

2. On the Perforce product download web page, find the version of P4FTP that is compatible with the platform where you intend to run it.

3. Download the file to the directory where you intend to run it.

   Note	Recommended installation directories are: Windows: C:\Program Files\Perforce\ UNIX: /usr/bin/ or /usr/local/bin/

Choosing a port number

• Command line: specify the -l flag when you start P4FTP.

• Windows service: use the p4 set -S command option to set the P4FTPORT environment variable for the service. For details, see "(Optional) Configuring P4FTP to start automatically" on page 11.

Starting P4FTP manually

1. Login as the user that you want to run P4FTP.

   UNIX	If you want to run p4ftpd on a privileged port (a port number lower than 1024), login as root. The default port for standard FTP servers is port 21. To enable P4FTP to listen on a privileged port while running as a user other than root, specify the -u username flag when you start p4ftpd.

2. Windows users: open a DOS window.

3. Run p4ftpd.

   When starting p4ftpd, you can specify the host and port number of the Perforce server you want to access, and optionally the port on which P4FTP accepts FTP commands.

   For example, to start p4ftpd with its default port (21) on the same computer (named perforce) where the Perforce server is running on its default port (1666), issue the following command:

   p4ftpd
   To start p4ftpd on port 1232 communicating with a Perforce server running on port 2343 on a remote computer named bigcomputer, issue the following command:
   p4ftpd -p perforce.bigcomputer.com:2343 -l 1232

[P4FTPD] Automatic changelist for uploaded files

For example:

p4ftpd -t "[P4FTP(%ftphost%)] submit by %user% from %client% at %time%"

(Optional) Configuring P4FTP to start automatically

UNIX computers

Windows computers

1. At the DOS command prompt, change to the directory where the file p4ftpd.exe is located. (This file is the one you downloaded from the Perforce web site.

2. Create a copy of p4ftpd.exe named p4ftps.exe by issuing the following command:

   cp p4ftpd.exe p4ftps.exe

3. Create a service by issuing the following command:
   svcinst CREATE -n "Perforce FTP Server" -e "fullpath/p4ftps.exe" -a
   where fullpath indicates that you must specify the full location of the p4ftps.exe file. Windows displays the following results:

   Creating Service         ServiceName=Perforce FTP Server         ExeName=c:\Program Files\perforce\p4ftps.exe         Autostart requested

   (To verify the service has been successfully created, use the Services control panel.)

   Note	The svcinst utility is installed when you install the Perforce server on Windows NT, in the same directory as the server. For more details, refer to http://www.perforce.com/perforce/technotes/note035.html

4. To specify a host and port for the service, issue the p4 set command. For example, to ensure that P4FTP listens on port 1892, issue the following command:
   p4 set -S "Perforce FTP Server" P4FTPPORT=1892

   You can also configure the user and client workspace name for the P4FTP service, for example:

   p4 set -S "Perforce FTP Server" P4USER=bruno

   p4 set -S "Perforce FTP Server" P4CLIENT=bruno

To start the service manually, use the Services control panel. The service starts automatically when you reboot your computer. To view settings, use regedit to display \\HKEY_SYSTEM\CurrentControlSet\Services\SERVICENAME\Parameters
where SERVICENAME is the name you gave the service when you created it.

Creating Perforce users and client workspace specifications

The following sections tell you how to create a Perforce users and client specification. Perform these steps from a computer where P4V or the Perforce command-line interface (p4) is installed. You can direct P4FTP to create a client specification using a template, when a user that has not P4FTP client specification connects for the first time. For details, see "Specifying a template for undefined client specifications" on page 17.

Using P4V

1. Launch P4V. The Open Connection dialog is displayed.

2. Click the New... button next to the User field. The New User dialog is displayed.

3. Enter the information for the user you want to create and click Save to dismiss the dialog.

4. Click the New... button next to the Workspace field. When prompted, enter "ftp-" followed by the name of the user you created in the preceding steps. The New Workspace dialog is displayed.

5. Enter the required information. Note that, because you define the client workspace on the computer where P4FTP runs, you only need to correct the normdir option. Check the following entries:

   Field	Description
   Host name	Specify the name of the computer where P4FTP runs. For example: mycomputer.mycompany.com.
   Root	Specify the directory on your FTP server computer where you want the Perforce client workspace to be located. P4FTP uses the client workspace as temporary local storage. Specify a location below the root directory, such as C:\p4client. To avoid cluttering the root directory of your client computer, do not use the root directory as the root of your client workspace. Choose a directory that is not used by another program or process.
   Options	Check rmdir. If your Perforce depot is located on a UNIX computer and your FTP client is located on a Windows computer, set the LineEnd option to win.
   View	Specifies the mapping of the Perforce depot to your client workspace, to determine which files in the depot are visible to your client computer. Do not change this entry unless you understand Perforce client views and want to alter the mapping.

6. Click Save to save your changes.

Using the P4 command-line interface

1. At the command line, issue the p4 user command. Perforce launches a text editor and displays the Perforce User Specification form as follows.

2. Enter the information for the new user in the User, Email, FullName, and (optionally) Password fields.

3. Save and close the file.

4. At the command line, issue the p4 client command. Perforce display the Perforce Client Specification form as follows:

5. Change the entries in the following fields:

   Field	Description
   Client	Specify "ftp-" followed by the Perforce user name.
   Host	Specify the name of the computer where P4FTP runs. For example: mycomputer.mycompany.com.
   Root	Specify the directory on your FTP client computer where you want the Perforce client workspace to be located. Recommendation: specify a location below the root directory, such as C:\p4client. To avoid cluttering the root directory of your client computer, do not use the root directory as the root of your client workspace.
   Client options	Change normdir to rmdir. If your Perforce depot is located on a UNIX computer and your FTP client is located on a Windows computer, set the LineEnd option to win.
   View	Specifies the mapping of the Perforce depot to your client workspace, to determine which files in the depot are visible to your client computer. Do not change this entry unless you understand Perforce client views and want to alter the mapping.

6. Save and close the file.

Specifying a template for undefined client specifications

The client template is an existing Perforce client specification. You define the client template as described in "Creating Perforce users and client workspace specifications" on page 12. To ensure that client roots do not conflict, you can use macros in the client root field of the template. For example, the following client root definition directs P4FTP to create a client root directory using the format /data/host/user:

Root: /data/%ftphost%/%user%

These definitions ensure that each user's client root is unique and map a user-specific depot path into their client view, along with files in the //depot/main/... path.

To specify the client template that you want P4FTP to use, specify the -T flag when you start p4ftpd. For example:

p4ftpd -T ftp-myclient-template

Using config files

• P4FTPPORT

• P4FTPPREFIX

• P4FTPLOG

• P4FTPSYSLOG (UNIX only)

• P4FTPCHANGE

• P4FTPTEMPLATE (template client specification; see "Specifying a template for undefined client specifications" on page 17)

Verifying your installation

Using the command line

1. At the operating system prompt, start FTP by issuing the ftp command.

2. At the ftp> prompt, issue the open command to connect to the host where P4FTP is running; for example, to connect to a host named "myhost" listening on port 1234:

   ftp> open myhost 1234

   The message "220 Perforce P4FTP FTP Server ready" is displayed.

3. If prompted, log in.

4. Display the contents of the Perforce depot by issuing the FTP ls command. To browse the depot and transfer files, use other standard FTP commands.

5. To display information about commands supported by P4FTP, issue the help command.

Using a Web browser

1. Launch a Web browser.

2. In the URL window, enter a URL that specifies FTP protocol, the Perforce user, and the P4FTP host name and port.

   For example, if P4FTP is running on mycomputer and listening on port 1850, enter:

   ftp://mitch@mycomputer:1850
   If you are using Internet Explorer, you must specify the user password (if any) in the URL in the following format:
   ftp://username:password@hostname:portnumber
3. If prompted, enter your password and click OK.

   The browser displays the contents of the depot. The following figure shows a browser displaying a depot.

Automatically syncing a Perforce client workspace

Valid options are as follows:

• -O autosync: Sync the entire client view every 300 seconds (five minutes).

• -O syncdelay=n: Sync every n seconds. The default interval is 300 seconds. If you specify this option, omit the -O autosync option.

• -O syncspec=valid_sync_specification: Sync only the specified files. valid_sync_specification can be any file specification you can use with the p4 sync command, including wildcards, labels or changelist numbers. By default, the entire client view is synced. If you specify this option, omit the -O autosync option.

You can specify these settings:

• when you start p4ftpd, or

• by setting the P4FTPOPTIONS environment variable before you start p4ftpd, or

• in a Perforce config file in or above the directory from which p4ftpd was started.

Example:  The following example sets p4ftpd to sync the entire client view every five minutes:

p4ftpd -O autosync

Example:  The following example sets p4ftpd to sync the files in the external_web directory every hour:

p4ftpd -O syncdelay=3600 -O syncspec=//external_web...

Example:  The following example shows how to specify the preceding settings in a config file.

P4FTPOPTIONS="syncdelay=3600,syncspec=//external_web..."

P4FTP configuration options

P4FTP startup options

For example, to start p4ftpd on the local machine on port 21, running with a non-root user and communicating with the Perforce server running on perforce.myorg.com on port 1666, issue the following command:

$ p4ftpd -p myftphost:1666 -l 21 -u p4ftpadministrator

Configuring Macromedia Dreamweaver with P4FTP

Overview

• Client workspace: an area of working storage on the computer where P4FTP runs. Must not overlap the local root.

• Local root: the directory where Dreamweaver stores its working copies of the web site files for editing.

• Host directory: a path relative to the root of your Perforce workspace, where Dreamweaver publishes the site's files.

• Client specification for "ftp-mitch"
  • Host: ftpserver

  • Client root: /usr/team/mitch

  • Client view: //depot/... //ftp-mitch/...

• Dreamweaver configuration for a Web site named "marketing99"
  • Local root: c:\dwroot\marketing99

  • Host Directory: /main/marketing99/

Creating web sites

1. Create a folder on your computer where you want Dreamweaver to store the local copies of your web site files. (Example: C:\mywebsite).

2. In Dreamweaver, choose Site>Manage Sites... The Manage Sites dialog is displayed.

3. Click New...

4. Enter the local settings for the new site, as illustrated in the following figure.

   Important: in the Local Root Folder field, specify an existing directory that does not reside in your client workspace root.

5. In the Category pane, click Remote Info. The Remote Info pane is displayed.

6. From the Access list, choose FTP. The following fields are displayed.

7. Make the following entries.

   Field	Description
   FTP Host	Enter the name of the computer where P4FTP is running and the port on which it is listening for FTP requests. For example: myftphost:1234
   Host Directory	The folder in the depot where you want to store your web site files. Specify this directory as a relative path (in other words, omit the client root directory) using the operating system convention of the computer where you run P4FTP.
   Login	Enter your Perforce user name.
   Password	Enter your Perforce password, if you have one.

   Check Enable file check in and check out only if you are working in a team environment, with locking enabled. See "Working in a team environment" on page 27 for details.

8. Click OK to save your entries.

Sample configuration

Perforce settings for client workspace

• "ftp-" client root: C:\ftproot

• "ftp-" client view: //depot/... //ftp-myuser/depot/...

Dreamweaver remote settings for site001

• Host directory: depot/websites/site001

Working in a team environment

• Start p4ftpd with the -O dwlocking option enabled. Note that dwlocking only works for Dreamweaver 2004 MX. For older releases use dw4locking.

• Choose Manage Sites>Remote Info and check Enable File Check In and Check Out. (Note that, when Dreamweaver locks a file, it creates a corresponding .LCK file.)

• Use Check In and Check Out, not Put and Get, when editing files.

(For details about defining Perforce users, see the Perforce Command Reference or use p4 help to display information about the p4 user command.)

After you enable locking for P4FTP, Dreamweaver and Perforce respect each other's file locks as follows:

• When you check out a file in Dreamweaver, it is opened for edit and locked in Perforce.

• When you open a file for edit and lock it in Perforce, Dreamweaver treats the file as checked out.

Updating a live web site

To set up a Web site so that, when you check files in using DreamWeaver, your live Web site is automatically refreshed, perform the following steps. This procedure assumes you already have a Web site created.

To configure automatic update, perform the following steps:

1. Create an ftp- client workspace for your Perforce user (example: ftp-tonyz).

   This workspace can be rooted anywhere on your machine -- it's a scratch area for P4FTP.

2. Create a web site client workspace, rooted in the content area of your web server.

   Example: if your web server is Microsoft IIS and you are creating a web site for Compass Adventures, create a workspace named compass-website., specifying the workspace root as C:\Inetpub\wwwroot

3. In the web server root, set up the web site files and verify that you can view them using a browser.

4. Using P4V or the p4 command-line client, add the files to the depot (using the web site client workspace you created in step 2).

   For example, add the files to the depot so they reside in //depot/Compass_WebSite/...

5. On the Web server machine, set P4CLIENT to the web site client workspace and start p4ftpd. For example, if your Perforce server is running on myserver:1999, issue the following command:

   p4ftpd -O dwlocking -O syncspec=//depot/Compass_WebSite/... -p myserver:1999

   By default, p4ftpd autosyncs every hour. To specify a different interval, use the -O syncdelay option.

6. Copy the web site files to a location on your machine where you intend to edit them using Dreamweaver (not in a client workspace). For example, copy the files to:
   C:\Program Files\Macromedia\Dreamweaver 4\Compass_WebSite
7. In Dreamweaver, define a web site (choose Manage Sites>New Site...) using the following settings:
   • Local info:

   Local root folder: the location where you want to edit files with Dreamweaver. For example: C:\Program Files\Macromedia\Dreamweaver 4\Compass_WebSite

   • Remote info:

   Access: FTP

   FTP host: machine and port where p4ftpd is running.; for example mywebserver:21

   Host directory: relative path to website files in depot, specified using local syntax. Leave blank if your web site files are located in a folder at the top level of the depot.

   Login: your Perforce user name.

   Enable check-in/check-out and fill in name and email.

8. Save your settings.

9. Right-click the top-level folder in the right pane and choose Put. Dreamweaver populates the left (Remote Site) pane.

The preceding approach uses a single instance of p4ftpd to support Dreamweaver check-in and to sync the web site. Alternately, you can use separate instances of p4ftpd for each purpose. Again, the instance that syncs the web site must reside on the machine where the web site files reside.

Troubleshooting notes: adding files

Click OK to dismiss the dialog. The depot directory is created (typically when you exit Dreamweaver).

Configuring HoTMetal PRO 6.0

1. Choose Tools>Sites...

2. Specify the name for your new site.

3. On the Choose Connection Method dialog, click the I connect to my site via FTP radio button and click Next.

4. On the FTP settings dialog specify the following:
   • Host Name: the computer where P4FTP runs

   • User ID: your Perforce user ID

5. If you intend to run P4FTP on a port other than the default (21), click Advanced FTP Settings... and specify the port on the Advanced FTP Settings dialog.

6. On the Choose FTP Default Folder dialog, specify the depot location for your web site. Example: depot/websites. The depot location must already exist. Note that, if P4FTP is running, you can click the browse button and browse the depot to specify the location.

Configuring Hot Dog Professional 6

1. Choose Open Remote... The Open dialog is displayed.

2. Double-click Add Internet Site. The Internet Site Wizard is launched.

3. In the What is your Server Address? field, specify the computer where P4FTP is running.

4. In the What is your Login Name? field, specify your Perforce user name. (If you have a password, specify it in the What is your Password? field.). Click Advanced.

5. In the Advanced Server Details dialog, specify the port number on which P4FTP is configured to listen (the value specified with the p4ftpd -l flag).

Configuring AceHTML

1. Choose File>Connect. The Session Properties dialog is displayed.

2. On the General tab, make the following entries:
   • Host Name: the name you want to assign to the host

   • Host Address: the fully-qualified domain name of the computer where P4FTP is running

   • User ID: your Perforce user name.

3. Click the Additional tab and enter the port number on which P4FTP is configured to listen (the value specified with the p4ftpd -l flag).

4. Click Connect.

5. If prompted, enter your Perforce password.