Perforce FTP Plug-in (P4FTP)

 

Overview

P4FTP is both an FTP server and a Perforce client which enables an FTP client to access files in Perforce depots. The P4FTP server accepts requests from FTP clients and communicates with a Perforce server.

To install, download the p4ftp binary and deposit in /usr/local/bin.

To connect from the command line, execute "ftp", and then from the prompt enter:

ftp> open hostname p4ftp_port

To connect from a Web browser, use a p4ftp URL. For example:

ftp://username:password@hostname:1666

 

Starting the Server

To start the p4ftp server process:

/usr/local/bin/p4ftpd -p perforce_host:perforce_port -l ftp_port

For example...

nohup p4ftpd -p hostname.com:1666 -l 10021 > /tmp/p4ftp.log 2>&1 &

The following start options are available:

Option Description
-c prefix Prefix applied to the username in order to derive the name of the Perforce client to use. Defaults to "ftp-" if not specified.
-d Run as a daemon process (UNIX only)
-f Run in single threaded mode. P4FTP will service one request at a time in this mode.
-h Print the command line syntax and exit
-i Started from inetd (UNIX only). Implies -f, because inetd creates a dedicated P4FTP for each request.
-l port Specify the TCP port number on which P4FTP listens for incoming connections. Defaults to 21 if not specified. On UNIX machines, only processes started by root can listen on ports below 1024.
-L logfile Redirect all log messages to the specified file. If not specified, error messages are directed to stderr
-p address Address of the Perforce server that serves the depot. Defaults to perforce:1666 if not specified
-s Redirect all log messages to the syslog daemon (UNIX only).
-t description Specify the description to be attached to all changelists created by P4FTP. Defaults to:

[P4FTP] Automatic changelist for uploaded files

There are various macros you can use to customize the description.
-v level Set verbosity level for debugging purposes.
-V Print version information and exit.

 

Configuration Options

Environment variable Description
P4FTPPORT Specifies the TCP port to listen on. The default port is 21.
P4FTPPREFIX Specifies the prefix to be prepended to the user's login to determine the corresponding Perforce client. The default prefix is "ftp-".
P4FTPCHANGE Specifies the description to be included when P4FTP submits changelists. Overrides the default description.
P4FTPLOG Specifies the file where P4FTP logs errors. By default, errors are sent to stderr.
P4FTPSYSLOG UNIX only: If set, enables logging using syslog().

p4ftpd obtains settings for P4USER, P4PASSWD and P4CLIENT from its FTP client and therefore ignores any config file entries for these settings. Any settings that you specify on the command line when you start p4ftpd override corresponding config file settings.

You can use Perforce config files to specify client options for p4ftpd:

  • P4FTPPORT
  • P4FTPPREFIX
  • P4FTPLOG
  • P4FTPSYSLOG (UNIX only)
  • P4FTPCHANGE
  • P4FTPTEMPLATE (template client specification;

 

User Setup

 

Using P4Win

  1. Launch P4Win.

  2. Choose User>New... The Create New User dialog is displayed.

  3. Enter the name of the user you want to create and click OK.

  4. Enter the required information and click Update.

  5. Choose ClientSpec>New... The Create New Client dialog is displayed.

  6. Enter "ftp-" followed by the name of the user you created in the preceding steps.

  7. 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.
    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.

 

Using the P4 command-line interface

To create a Perforce user and client specification using the Perforce command-line interface, perform the following steps.

  1. At the command line, issue the p4 user command.

  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.

  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:
    Root Specify the directory on your FTP client computer where you want the Perforce client workspace to be located.
    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.

 

Specifying a template for undefined client specifications

To enable P4FTP to create an "ftp-" client specification for users that lack one, you can specify a template client specification. The first time a user that lacks an "ftp-" client specification connects, p4ftpd creates an "ftp-" client specification based on the client template. If you do not specify a template, P4FTP requires all "ftp-" client specifications to exist when it attempts to connect to the Perforce server.

The client template is an existing Perforce client specification. You define the client template as described in "Creating Perforce users and client specifications" on page 11. 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%

To ensure that client roots do not conflict, and to tailor the client view to meet your needs, you can use macros in both the client root field and the view field of the template. For example:. 

Root:   /data/%c
View:   //depot/main/... //%client%/main/...
        //depot/user/%user%/... //%client%/%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

 

Saving files

When you use the put command from an FTP client, your files are added to a Perforce changelist in preparation for submission to the depot. When you close your connection, the changelist is submitted and the files are saved to the depot.

When you use the Save or Publish feature of your web authoring tool, your files are added to a Perforce changelist in preparation for submission to the depot. When you disconnect from P4FTP, the changelist is submitted and the files are saved to the depot. Note that a newly uploaded file is not visible to other P4FTP or Perforce users until the submitting user closes its FTP connection.

 

Getting files

When you use the get command from an FTP client, the Open feature of your web authoring tool, or download a file using a Web browser, the files are synced from the depot to your client computer and are immediately visible on the client computer.

 

The pwd command

The FTP command pwd (print working directory) normally displays the current directory on the remote computer. When you use P4FTP, the pwd command displays the Perforce depot directory but uses the client OS convention.

For example, if you are connecting from a Windows computer to a depot on a UNIX computer, when you issue the pwd command, the working directory might be displayed as c:\p4client-test\depot.

 

Supported FTP commands

The following table lists the FTP commands that are supported by P4FTP. The names in braces are the commands used by common FTP clients, and the uppercase names represent the actual protocol commands.

ACCT account
RETR get
CDUP cdup
RNFR rename
CWD cd
RNTO rename
DELE delete / rm
SIZE size
LIST ls / dir
STAT rstat
MDTM modtime
STOR put
MKD mkdir / md
STRU stru
NLST nlist
SYST system
TYPE ascii / binary
USER user
PASV passive
XCWD cd
XCDUP cdup
PWD pwd
XMKD mkdir / md
QUIT quit / bye
XPWD pwd

 

Changelist numbering

P4FTP uses only the default changelist. If a submit fails for any reason, Perforce turns the default changelist into a numbered changelist. To ensure that files opened under numbered changelists do not become abandoned, P4FTP consolidates all files opened on a client into the default changelist. Users can resolve most problems by simply retrying, without the assistance of an administrator.

 

Changelist descriptions

Due to the design of the FTP protocol, P4FTP cannot prompt the user for a description when a changelist is submitted, so a default description is used. If the ability to describe changelists is important to you, use the P4 command line client or P4Win.

To override the default change description, specifying the desired description using the -t command line flag when you start P4FTP.

 

Filetypes

For new files being uploaded to the server, P4FTP uses the Perforce filetype detection mechanism to determine whether a file is a text file or a binary file. For files that already exist on the server but are being updated, P4FTP uses the filetype of the previous revision so that files marked as ktext or binary+S, for example, retain this type of information.

 

Workspace management

Because P4FTP uses its client workspace only for temporary storage, users do not need to sync to keep the workspace up to date. P4FTP stores the following types of files in the client workspaces:

  • Files uploaded by the user and open for add or edit
  • Files being downloaded to the user and synced to the head revision
The client workspace used by P4FTP provides:

  • An isolated area of temporary storage.
  • An identifier for Perforce to use to track open files and submissions.
  • A workspace that an administrator can use to correct errors.

After every successful submission, all files in the submitted changelist are removed from the client workspace using p4 sync filename#none. When a user requests a file from P4FTP using the FTP get command, P4FTP retrieves the head revision of the file from the depot, transfers it to the user and then removes it from its workspace by syncing it to #none. This feature enables large areas of the depot to be mapped without wasting disk space.

The only files that are typically present in the client workspace are files that the user is actively using. To prevent empty directories from cluttering the client workspace, you enable the rmdir option when you create clients specifications.

To diagnose client workspace problems, use the p4 command or P4Win.

 

Concurrency

All files opened for add or edit and delete are locked by P4FTP to prevent other users from submitting their change first and thereby denying P4FTP access to the head revision. If a file is locked when a user tries to upload it using P4FTP, permission is denied until the lock is released.

 

Changelist Descriptions

The following macros are available for descriptions when used with the -t upon p4ftp startup:

Macro Expands to
%user% user name
%client% client name
%ftphost% host name (p4ftpd host)
%time% timestamp

For example:

p4ftpd -t "[P4FTP(%h%)] submission by %u% from %c% at %t%"