.TH p4dctl.conf 5 "March 2014" Linux "File Formats"
.SH NAME
p4dctl.conf \- configuration for p4dctl
.SH DESCRIPTION
This man page describes the file format for p4dctl, a tool
for managing multiple Perforce services on a Linux/Unix
host.
.SH SYNTAX
A p4dctl config file is made up of a series of blocks of the following
types:
.TP 5
Settings
Settings specified globally (i.e. not inside a Server block) are
merged into the settings of all servers.
.TP
Environment blocks
Define environment variables to be applied globally to all servers. Usually
there is only one global environment block, but if there is more than one,
then they are merged together with the later blocks taking precedence over
earlier ones.
.TP
Server Blocks
The definitions of specific server processes to be managed by p4dctl
.P
We will now discuss these blocks in detail.
.SS Settings
Settings are options that control the behaviour of p4dctl itself,
as opposed to being configuration for the servers that p4dctl manages.
A setting statement simply takes the form:
.P
.RS
.I <setting name>
=
.I <setting value>
.RE
.P
See SETTINGS below for details of the available settings.
.SS Environment Blocks
.P
Environment blocks use a very simple syntax:
.P
.RS
.B Environment
.br
{
.RS
.I <variable>
=
.I <value>
.br
...
.RE
.br
}
.RE
If an environment block occurs within the scope of a server
block (See Server Blocks, below), then the variables defined
will only be set within the environment of that server's
processes.
.P
If the environment block occurs outside of any server block,
then the variables it contains will be applied to the environment
of all processes created by p4dctl.
.SS Required Environment Variables
.P
Some types of server require that specific environment variables
are defined. See the notes on the specific server types below
for more information.
.SS Server Blocks
.P
Server blocks form the basis of all p4dctl configuration. Each
block specifies a server process to be managed by p4dctl. The
syntax for a server block looks like this:
.P
.RS
.I <server type>
.I <server name>
.br
{
.RS
.I <setting>
=
.I <value>
.br
...
.br
.B Environment
.br
{
.RS
.I <variable>
=
.I <value>
...
.RE
.br
}
.RE
.br
}
.RE
.P
Where
.I <server type>
is one of:
.br
.RS
.TP 15
p4d
Perforce Server
.TP
p4p
Perforce Proxy Server
.TP
p4broker
Perforce Broker
.TP
p4ftp
Perforce FTP Plugin
.TP
p4web
Perforce Web client
.TP
other
Any other service
.RE
.P
And
.I <server name>
is your name for this server. Names must be unique to servers
of a given type, but may be re-used across types. This can be
used to start/stop groups of servers that share the same name.
For example, a configuration that defines p4d, proxy and p4ftp
servers all called 'main' can use:
.P
.RS
p4dctl stop main
.RE
.P
To stop all of those servers at once without affecting any other
services.
.P
For valid settings and their values, see SETTINGS, below.
.SH SETTINGS
The following settings may be applied within server blocks
.SS Owner
Specifies the owner of the service. The service will be started
under that user's account and with their privileges. The user
may also use p4dctl to manage servers they own.
.SS Execute
The path to the binary to execute when starting this server
.SS Args
A string containing the arguments to be passed to the binary
specified with
.I Execute.
.SS Enabled
If set to false, the service is disabled and will not be
started. (default:true)
.SS Umask
Set to an octal value specifying the umask to be applied to
the child processes for this server. The default umask on
most Linux/Unix systems is 022, which means all new files
will be readable by all users. Setting the Umask to 077
ensures that the files created by this service will only
be accessible to the
.I Owner
of the server.
.SS Prefix
A string containing a prefix to apply when checkpointing
or rotating the journal. This prefix will be passed down
to the relevant
.I p4d
command. (default: none)
.SS PrettyNames
If true, p4dctl will format the process names of the server
processes it starts in a way that is pleasing to the author.
Your mileage may vary. (default:true)
.SH INCLUDING FILES/DIRECTORIES
p4dctl allows you to modularize your configuration into
separate files or directories and include those into
your configuration.
.SS Including files
.P
To include a specific file, use the following syntax:
.P
.RS
.BI include " <path to file>"
.RE
.SS Including directories
.P
When including directories, p4dctl requires that names
of the included files end in ".conf".
.P
Directories can be included like this:
.P
.RS
.BI include " <path to directory>"
.RE
.P
See the EXAMPLES section below for more examples of
including files.
.SH SERVER TYPES
.SS p4d
.B Required Settings
.RS
.TP 20
Owner
Owner of the server (cannot be root)
.TP
Execute
Path to the p4d binary
.RE
.P
.B Required Environment Variables
.RS
.TP 20
.B P4PORT
Port to use for this server
.TP
.B P4ROOT
Path to this server's root directory
.TP
.B PATH
Search path to be used for this server
.RE
.SS p4p
.B Required Settings
.RS
.TP 20
Owner
Owner of the server (cannot be root)
.TP
Execute
Path to the p4p binary
.RE
.P
.B Required Environment Variables
.RS
.TP 20
.B P4PORT
Port to use for this server
.TP
.B P4TARGET
Address of the target Perforce Server
.TP
.B P4PCACHE
Path to this proxy's cache directory
.TP
.B P4ROOT
Path to this server's root directory
.TP
.B PATH
Search path to be used for this proxy
.RE
.SS p4broker
.B Required Settings
.RS
.TP 20
Owner
Owner of the server (cannot be root)
.TP
Execute
Path to the p4broker binary
.RE
.P
.B Required Environment Variables
.RS
.TP 20
.B P4BROKEROPTIONS
Command line options to pass to this broker. Used to
specify the path to the broker's configuration file.
.RE
.SS p4ftp
.B Required Settings
.RS
.TP 20
Owner
Owner of the server (cannot be root)
.TP
Execute
Path to the p4ftpd binary
.RE
.P
.B Required Environment Variables
.RS
.TP 20
.B P4PORT
Address of the target Perforce Server
.TP
.B P4FTPPORT
Port to use for serving FTP requests
.RE
.SS p4web
.B Required Settings
.RS
.TP 20
Owner
Owner of the server (cannot be root)
.TP
Execute
Path to the p4web binary
.RE
.P
.B Required Environment Variables
.RS
.TP 20
.B P4PORT
Address of the target Perforce Server
.TP
.B P4WEBPORT
Port to use for serving HTTP requests
.RE
.SS other
.B Required Settings
.RS
.TP 20
Owner
Owner of the server (cannot be root)
.TP
Execute
Path to the binary
.RE
.P
There are no required environment variables for servers
of this type.
.SH EXAMPLES
.SS Basic Perforce Server configuration
.RS
p4d minimum
.br
{
Owner = perforce
Execute = /usr/sbin/p4d
Environment
{
P4ROOT = /home/perforce/p4-main
P4PORT = 1666
PATH = /bin:/usr/bin:/usr/local/bin
}
.br
}
.RE
.SS Server and Proxy
Note in this example that the PATH environment variable
is defined once, globally for both servers.
.RS
Environment
.br
{
PATH = /bin:/usr/bin:/usr/local/bin
.br
}
p4d master
.br
{
Owner = perforce
Execute = /usr/sbin/p4d
Environment
{
P4ROOT = /home/perforce/p4-main
P4PORT = "localhost:1667"
}
.br
}
p4p master
.br
{
Owner = perforce
Execute = /usr/sbin/p4p
Environment
{
P4PCACHE = /home/perforce/proxy-main
P4PORT = 1666
P4TARGET = "localhost:1667"
}
.br
}
.RE
.SS Multiple File Configuration
.RS
Environment
.br
{
PATH = /bin:/usr/bin:/usr/local/bin
.br
}
include /etc/perforce/p4dctl.conf.d
.RE
.SH SEE ALSO
.BR p4dctl (8)
.BR p4d (1)
.BR p4 (1)