Linux/Unix Setup and Execution

We strongly recommended that you first acquaint yourself with the Browse Benchmark on an isolated test machine before executing the benchmark on a production machine. This benchmark must be kept separate from any existing Perforce installations.

Important: The value for the benchmark's P4ROOT definition must not be the same as an existing Perforce installation.

Prerequisites

  • License - If you don't already have a Perforce license for the machine on which the server for this benchmark will run, you'll need to acquire a temporary license from either sales@perforce.com, labs@perforce.com, or support@perforce.com. The number of users licensed must be equal to the maximum number of browsechild instances that you intend to use. The default number of children is 64.
  • Diskspace - You need ample diskspace to accommodate the database metadata files that will be used. If the Browse Benchmark is run over an extended period, the diskspace required for log file growth might need to be considered. Additionally, the log file from a completed run will be moved to the directory where the browse script is initiated. As a result, the same amount of diskspace required at P4LOGdir is also necessary in the partition where the browse script is executed.
  • SSH - The Browse Benchmark requires SSH. It must be available on both the server and client computers. SSH is generally pre-installed on Linux/Unix. If you are including Windows machines within the benchmark topology, they are also required to have SSH installed. There are several Windows ports of SSH available, however, not all supply the functionality required by the Browse Benchmark. We have found that Cygwin and CopSSH have the required functionality. Whichever SSH you decide to use, we recommend reading the documentation. For your convenience, we have supplied a high-level overview of the installation process for Cygwin and CopSSH.

Setup Procedure

  1. Ensure that SSH is installed on the server machine and that sshd is listening on all machines used as clients. This can be verified by executing the following command from the server machine: 
     ssh <client-machine> echo Hello World!
    You must verify the SSH connection to each client machine.
  2. The browse public/private key pair allows the browse script to launch children on the client machines using SSH without entering a password. Add the browse public key, browse.pub, to ~/.ssh/authorized_keys for your user on all the client machines. The browse public/private key pair can be verified by executing the following command from the server machine: 
     ssh -i browse <client-machine> echo Hello World!
    You must verify the SSH connection to each client machine. If the browse public/private key pair is working correctly, no password or passphrase is required.
  3. In browse.sh, modify the existing default values for the following variables.
    • The first portion of the browse script defines the utilities used in the script. If any of these utilities are not in your path, their definition can be changed to their absolute location, or to suitable alternative utilities. Of particular note are the definitions for p4 and p4d. Their definitions can be changed to use specific releases:

      p4=/<path_to_p4_binary>/p4
      p4d=/<path_to_p4d_binary>/p4d
    • The next portion of the script defines filesystems and other variables used in the script. The definitions for the following will need changed to values that are suitable for your site:

      P4PORT
      P4ROOT
      P4JOURNALdir
      P4LOGdir
      ZCKP

      The value for the P4PORT definition should not be a port on which a production Perforce server is listening. If the port for a production Perforce server is used and many browsechild instances are configured, users of the production Perforce server might experience unexpected performance.

      The browse script creates the P4ROOT, P4JOURNALdir, and P4LOGdir directories if they do not already exist. The directories used for this benchmark must not be part of any existing Perforce installation. If the values for the P4ROOT, P4JOURNALdir, and P4LOGdir definitions are part of an existing Perforce installation, the existing installation can be corrupted.

      The ZCKP definition must be the compressed checkpoint of the metadata that will be used in the benchmark. This is a compressed checkpoint of the reference01 metadata or site-specific metadata. The db.* files are created using the compressed checkpoint during the script's "setup" phase.

      IMPORTANT: The reference01.<version>.ckp.gz dataset requires a P4ROOT partition that has at least 44GB of space available.

    • HOSTS=<host>=<platform>[,[<children>][,[<browses>][,[<connection>][,[<seed>][,[<user-offset>]]]]]]

      The HOSTS setting requires some special attention. The values placed in HOSTS directly affect configuration and execution of the browsechild program. The tokens of the HOSTS variables are represented as follows:

      Token Description
      <host> Required - Defines the name of a client machine used in the benchmark topology. The browschild program is deployed to this host where it will be launched using any/all of the subsequent defined values. Each client <host> along with its subsequent defined values is delimited with a space.
      <platform> Required - Identifies the architecture of the client machine. This value should match the OS portion of the directory where the browsechild binary is stored locally within the Browse Benchmark package. For example: The platform value of "ntx86" would be used to access the browsechild.exe file from the bin.ntx86 directory.
      <children> Optional - Defines the number of children dispatched to the client machine. For example, if this value is set to 10, you will observe ten browsechild processes in the process status (ps) output on the client machine. If not set, the default value is 32 children.
      <browses> Optional - Defines the number of browses that each browsechild instance on the client machine performs. If not set, the default value is 1024 browses.
      <connection> Optional - Defines the type of connection each browsechild instance on the client machine uses while browsing. Valid values are: b, 1 and c.
      b = per browse (establish a new connection for each browse - default)
      1 = single (a single connection is maintained for all browses)
      c = per command (each command is issued on a new connection)
      <seed> Optional - If the base of the pseudo-random number generator seed is specified, the actual seed is calculated for each browsechild instance. Specifying a seed is useful when reproducible, randomized benchmark runs are required. Prime numbers are generally good seeds and different seeds should be used for each host, e.g. 12073, 22073, 42073, 72073, 82073, etc.
      <user-offset> Optional - Offset added to the generated user identifiers. For example, if a user offset of 73 is specified, the resulting generated user identifiers are user00074, user00075, etc. The default user offset is zero; not specifying a user offset results in the generated user identifiers user00001, user00002, etc.
    • LICENSE

      This is the location from where the license is copied.

      IMPORTANT: You should not place the license file in the P4ROOT directory. During the "cleanup" phase the copied license file located in the P4ROOT directory will be deleted.

    • SIDENTITY

      SIDENTITY defines the name of the identity used by SSH client on the server machine when authenticating to the SSHD daemon on the client machines. By default, SIDENTITY is set to use the "browse" identity. This makes the assumption that you are using the browse identity files included with the Browse Benchmark package. Be aware that using an identity file that is shared/known outside your organization might be security risk.The "browse" identity files provide passwordless authentication. If necessary, you can generate your own keys using the same model. If you generate your own files and use a name other than "browse", you will need to update the SIDENTITY value accordingly.

    • SUSER

      By default, SUSER is set to the current login name. This is the login account that is used by ssh to connect to the client machines. If you use an alternative name, you must verify that the user has appropriate privileges to connect and perform operations on the client machines.

    • TMPPOSIX and TMPWINDOWS

      When the browse script deploys the browsechild program to each client machine, it is copied to the operating system specific tmp directory. On Linux/Unix it utilizes TMPPOSIX which defaults to the /tmp directory. On Windows, TMPWINDOWS is used and defaults to $TMP which translates to the tmp location identified by the Window SSHD daemon installed on your client machines. If you decide to change the values for TMPPOSIX and TMPWINDOWS to alternative locations, verify that appropriate permissions are available for file copy and execute operations.

  4. Run the benchmark: 
     ./browse.sh

    When executed using no arguments, the script executes the "setup" phase, the "runme" phase, and then the "cleanup" phase. The "setup" phase creates the db.* files using the compressed checkpoint and then starts the server. The "runme" phase launches the browsechild instances on the client machines, analyzes the server log, and reports the results. The "cleanup" phase stops the server and deletes the db.* files, the copied license file and the journal used in the benchmark.

    Specific phases of the benchmark can be executed by the script. The script will execute each phase as specified by the arguments given to the script. For example, if executing the "setup" phase and three instances of "runme" phase is desired, the script would be invoked as:

    ./browse.sh setup runme runme runme

    You can run each of the phases individually so that you can run multiple "runme" phases without having to replay the checkpoint:

    ./browse.sh setup
./browse.sh runme 
./browse.sh runme
. 
.
. 
./browse.sh runme 
./browse.sh cleanup
  5. The following is a results example. For more information, see Results Analysis: 
    Summarizing server log...
  64 children over 2 hosts browsed for 101 seconds.
  32 children ran concurrently from 2012/01/09 13:58:58 to 2012/01/09 13:59:02.
  maximum fstat/second: 11151 at 2012/01/09 13:58:39 (13 concurrent children).
  maximum filelog/second: 1011 at 2012/01/09 13:58:39 (13 concurrent children).
  65536 total browses browsed 65445 unique filepaths.