Perforce Server Control (p4dctl)

The Perforce Service Control (p4dctl) utility allows you to manage Perforce services running on the local host. Non-root users can administer the services they own, while root may administer all services, but may not own any.

Note

p4dctl can only be obtained as part of the UNIX package installation. It is not supported on Windows.

You use the p4dctl utility to configure the environment in which services run and to manage the services themselves. The basic workflow for an administrator using the p4dctl utility is as follows:

Edit a configuration file that defines the environment for the services you want to control.
Execute p4dctl commands to start and stop services, to get information about services, and to checkpoint services.

You can use a single p4dctl command to manage all services or an arbitrary group of services by assigning them a common name in the p4dctl configuration file.

p4dctl introduces no new environment variables; it enforces strict control of the environment of any service it starts according to the directives in the p4dctl configuration file. This prevents failures that stem from the differences between the user’s environment and that of root.

Installation

p4dctl is installed as part of the UNIX package installation. The installation process automatically creates a master configuration file located at /etc/perforce/p4dctl.conf.

As part of the package install, p4dctl is installed as a setuid root executable because it uses root privileges to maintain pid files for compatibility with systems that use them. For all other operations, p4dctl runs with the privileges of the executing user. This allows non-root users to start and stop the services they own while having the pid file remain up to date.

Configuration file format

p4dctl uses a configuration file, p4dctl.conf, to control the following:

service settings for the services started with the p4dctl command.
settings for the p4dctl utility itself
service processes managed by p4dctl, for example checkpointing and journal rotation
the environment in which managed services are running

The environment is configured using environment variables that may be defined globally or for a specific service. The service type determines which variables must be defined. See Service types and required settings for information on the requirements for each type.

A p4dctl configuration file is made up of an environment block and one or more server type blocks. The following sections describe each type in detail.

The configuration file may also contain comments; these are designated by starting the comment line with the # sign.

Settings specified outside of a server block are global and are merged into the settings of all services. They take the following form:

setting_name = value

For example:

PATH = /bin:/user/bin

Environment block

An environment block defines environment variables that are applied to one or more services. You can have more than one environment block. Server-specific environment blocks settings override corresponding settings in global environment blocks.

An environment block is defined using the following syntax:

Environment
{
   variable = value
}

An environment block may be used outside of a server block or inside of it.

If the block is outside a server block, the variables it contains are applied to the environment of all processes created by p4dctl.
If the block is inside a server block, the variables it defines are set only in the environment of that server’s processes, but they do override corresponding settings at the environment level.

For example, the following settings outside a server block ensure that the owner is set to perforce, logging is enabled, and the correct P4CONFIG files are used.

Environment
{
     P4DEBUG     =  "server=1" # Embedded = requires quotes
     P4LOG       =  log
     P4CONFIG    =  .p4config
}

Server block

A server block defines settings and variables that apply only to the specified type of service. Type may be one of the following:

Type	Meaning
`p4d`	Perforce server
`p4p`	Perforce proxy server
`p4broker`	Perforce broker
`p4ftp`	Perforce FTP plugin
`p4web`	Perforce web client
`other`	Any other service

A server block is defined using the following syntax:

server_type name
{
   setting = value
   Environment
   {
       variable = value
   }
}

The specified name name must refer to services of a given type, but the name can include different types of servers. This allows you to control or query groups of heterogeneous servers that share the same name.

For example, a configuration that defines p4d, proxy, and p4ftp services all using the name main can use a command like the following to stop all these services without affecting any other services.

$ p4dctl stop main

You can define the following variables within server blocks. Owner and Execute are required for all server types.

Setting	Meaning
`Owner`	The owner of the service. The service is started under the owner’s account and with their privileges. The user can also use `p4dctl` to manage the server they own. Required.
`Execute`	The path to the binary to execute when starting this server. Required.
`Args`	A string containing the arguments to be passed to the binary specified with `Execute`. The string must be quoted if it contains a space.
`Enabled`	Set to `FALSE` to disable the service and not start it with the `p4dctl start` command. Default: `TRUE`
`Umask`	An octal value specifying the `umask` to be applied to the child processes for this service. The default `umask` on most Linux/Unix systems is 022, which means all new files are readable by all users. Setting this variable to 077 ensures that the files created by this service are only accessible to the owner of the service.
`Prefix`	A string containing a prefix to apply when checkpointing the server or rotating the journal. This prefix is passed down to the relevant `p4d` command if needed. Default: none
`PrettyNames`	Set to `true` to have `p4dctl` format the names of the server processes it starts, in an informative way. In the following example, the `p4d` process is qualified with its host and port name when `PrettyNames` is set to true. PrettyNames=true perforce callto:21397%201%200%2010[21397 1 0 10]:48 ? 00:00:00 p4d [blacksphere/1666] PrettyNames=false perforce callto:21725%201%200%2010[21725 1 0 10]:50 ? 00:00:00 /usr/sbin/p4d Default: true

Service types and required settings

Each service type requires that you define the owner of the server (which cannot be root) and the execute path where its binary can be found. For example, for the p4d type, you specify the path to the p4d binary, for the broker, you must provide the path to the p4broker binary, and so on.

For each service type, you must also define certain environment variables; these are listed in the following subsections.

Type	Variable	Setting
`p4d`	`P4PORT`	Port to use for this service
	`P4ROOT`	Path to the server’s root directory
	`PATH`	Search path to be used for this service
`p4p`	`PORT`	Port to use for this service
	`P4TARGET`	Address of the target Perforce service
	`P4ROOT`	Path to the server’s root directory
	`PATH`	Search path to be used for this service
`p4broker`	`P4BROKEROPTIONS`	Command line options to pass to this broker
`p4ftp`	`PORT`	Address of the target Perforce service
	`P4FTPPORT`	Port to use for serving FTP requests
`p4web`	`PORT`	Address of the target Perforce server
	`P4WEBPORT`	Port to use for serving HTTP requests
	`P4ROOT`	Path to the server’s root directory
	`PATH`	Search path to be used for this service

Configuration file examples

The following example shows a basic Perforce server (p4d) configuration file.

p4d minimum
{
  Owner   = perforce
  Execute = /usr/bin/p4d
  Environment

  {
   P4ROOT     = /home/perforce/p4-main
   P4PORT     = 1666
   PATH       = /bin:/usr/bin:/usr/local/bin
  }
}

In the following example, the PATH environment variable is defined once, globally for both the service and its proxy. Note how the name 'test' is used to refer to both.

Environment
{
  PATH       = /bin:/usr/bin:/usr/local/bin
}

p4d test
{
  Owner   = perforce
  Execute = /usr/bin/p4d

Environment
  {
   P4ROOT     = /home/perforce/p4-main
   P4PORT     = "localhost:1667"
  }
}

p4p test
{
  Owner   = perforce
  Execute = /usr/bin/p4p

  Environment
  {
   P4ROOT     = /home/perforce/proxy-main
   P4PORT     = 1666
   P4TARGET   = "localhost:1667"
  }
}

Using multiple configuration files

You can modularize your configuration by creating multiple configuration files and directories and including these in your configuration.

To include a specific file, use the following syntax:
```
include pathToFile
```
To include directories, use the following syntax:
```
include directoryPath
```
When including directories, p4dctl requires that names for files included end in .conf.

The following example shows a multiple file configuration.

Environment
{
  PATH       = /bin:/usr/bin:/usr/local/bin
}

  include /etc/perforce/p4dctl.conf.d

p4dctl commands

p4dctl commands can be divided into three categories: commands that stop and start services, commands that checkpoint services, and commands that return information about services.

The p4dctl checkpoint command is similar to the p4d -jc command.

The following table presents a summary of command syntax for each category. The parameter -a specifies all servers.

Category	Syntax
Control services	`p4dctl [ options ] start [ -t type ] -a` `p4dctl [ options ] start [ -t type ] name` `p4dctl [ options ] stop [ -t type ] -a` `p4dctl [ options ] stop [ -t type ] name` `p4dctl [ options ] restart [ -t type ] -a` `p4dctl [ options ] restart [ -t type ] name`
Checkpoints and journals	`p4dctl [ options ] checkpoint -a` `p4dctl [ options ] checkpoint name`
Query services	`p4dctl [ options ] status [ -t type ] -a` `p4dctl [ options ] status [ -t type ] name` `p4dctl [ options ] list [ -t type ]` `p4dctl [ options ] list [ -t type ] name` `p4dctl [ options ] env [ -t type ] -a var [var…]` `p4dctl [ options ] status [ -t type ] name var [var…]`

Options to p4dctl commands are described in the following table. The meaning of variable names other than option names is explained in Configuration file format.

Options	Meaning
`-c configFile`	Path to the configuration file Default: `/etc/perforce/p4dctl.conf`
`-p pidDir`	Path to the pid file directory. Default: `/var/run`
`-q`	Send output to syslog instead of `STDOUT` or `STDERR`
`-v level`	Set debug level (0-9) For more information, see the description of the `P4DEBUG` environment variable in P4 Command Reference.
`-V`	Display version and exit.

Helix Versioning Engine Administrator Guide: Fundamentals (2016.2)

Perforce Server Control (p4dctl)

Note

Installation

Configuration file format

Environment block

Server block

Service types and required settings

Configuration file examples

Using multiple configuration files

p4dctl commands