P4dctl.md #1

About p4dctl

P4DCTL is a tool that allows the administrator to describe and control all the Perforce services running on a unix machine in a single textual config file and allows root and non-root users to start and stop the services (as permissions allow.)

P4DCTL can be used to manage the Perforce Server (p4d), Proxy (p4p), Broker (p4broker), FTP daemon (p4ftpd) and the Perforce Web client (p4web). P4DCTL is used as part of the Perforce Server RPM/DEB packages for linux (http://package.perforce.com/)

For more information, please see the manpage for p4dctl and p4dctl.conf.

Features

Common interface for root and non-root users
Non-root users limited to services they own
Central configuration of all services
Bulk start/stop of services
- all services
- all services of a particular type
- all services by name
Easy way to check status of all services
Maintains pidfiles under /var/run
Sets process name intelligently (e.g. 'p4d [main/1666]' )
Designed to be a secure setuid root executable

Installation

Most people should build p4dctl from the source. To do so, you'll need the Perforce C++ API for your platform, a suitable C++ compiler, Flex, Byacc and Perforce Jam.

jam -a -sP4=<absolute path to the P4 C++ API> -sOSVER=<version>

jam -sP4=<absolute path to the P4 C++ API> -sOSVER=<version> install

Then copy p4dctl/src/p4dctl.conf.sample to /etc/perforce/p4dctl.conf

Configuration

For security reasons, the configuration file path is hard-coded into p4dctl: /etc/perforce/p4dctl.conf. This ensures that only a privileged user can create or edit the file.

A sample configuration looks like this:

#-------------------------------------------------------------------------------\ # Global environment variables - passed to ALL services\ #-------------------------------------------------------------------------------\ P4DEBUG = server=3\ P4LOG = log\ P4CONFIG = .p4config\ \ #-------------------------------------------------------------------------------\ # Server specifications\ #-------------------------------------------------------------------------------

p4d main\ {\ Owner = perforce\ Execute = /usr/local/bin/p4d\ Umask = 077\ Environment\ {\ P4ROOT = /home/perforce/p4-main\ P4JOURNAL = journal\ P4PORT = 1666\ PATH = /bin:/usr/bin:/usr/local/bin\ }\ }

p4web main\ {\ Owner = tony\ Execute = /usr/local/bin/p4web\ Args = "-b"\ Environment\ {\ P4WEBPORT = 8080\ P4PORT = 1666\ P4CLIENT = p4webclient\ PATH = /bin:/usr/bin:/usr/local/bin\ }\ }

Notice that the service is given a name (in this case both services use 'main'), and an owner. The idea is that only root, and the user 'perforce' can manipulate the main servers, and the environments of the servers are tightly controlled.

Support

For assistance, please contact Perforce Support (support@perforce.com)

For an official Perforce supported version of P4DCTL please install it via http://package.perforce.com/

Example Usage

Using the configuration file above, here are some example commands showing how p4dctl can be used:

Starting All Services

p4dctl start -a

Starting All P4D Servers

p4dctl start -a -t p4d

Starting All Servers by Name

p4dctl start main

Note that the example above would start both the P4D and P4Web servers - quite a simple way of managing groups of servers.

Sample Init Script

This is where it all started, so there wouldn't be much point in doing this if I didn't show you how to use this in an init script! Here's the one I use on Debian boxes:

#!/bin/bash\ \ ### BEGIN INIT INFO\ # Provides: p4dctl\ # Required-Start: \ # Required-Stop: \ # Default-Start: 2 3 4 5\ # Default-Stop: 0 1 6\ # Short-Description: Start Perforce services at boot time\ # Description: This script starts all Perforce services managed\ # by p4dctl as configured in /etc/p4d.conf.\ ### END INIT INFO\ \ # Source init-function library containing e.g. log_daemon_msg\ . /lib/lsb/init-functions\ \ PROG=/usr/local/bin/p4dctl\ [ -x $PROG ] || exit 0\ \ case "$1" in\ start) log_begin_msg "Starting Perforce services..."\ $PROG -q start -a\ log_end_msg $?\ ;;\ stop) log_begin_msg "Stopping Perforce services..."\ $PROG -q stop -a\ log_end_msg $?\ ;;\ restart) log_begin_msg "Restarting Perforce servicesa..."\ $PROG -q restart -a\ log_end_msg $?\ ;;\ *) log_success_msg "Usage: /etc/init.d/p4d start|stop|restart"\ exit 1\ ;;\ esac\ exit 0

Obviously there's some Debian-specific stuff in there, but the main point is that the simple act of starting and stopping all services is reduced to a one-liner.

Downloads

There are a couple of Linux binaries available from the Public Depot that people are welcome to use. If other platforms are required, please contact me.

Command Line Syntax

Global Syntax

p4dctl [global options] <command> [options] [<service name>]\ \ Where 'global options' are:\ \ -c <path> Path to configuration file (/etc/p4d.conf)\ -p <pid path> Path to pid file directory (/var/run) \ -q Quiet mode\ -v Verbose output\ \ Recognised commands are:\ \ start Start specified servers\ stop Stop specified servers\ restart Restart specified servers\ status Check the status of specified servers\ checkpoint Checkpoint specified P4D servers\ journal Rotate journals of specified P4D servers

Start Command Syntax

p4dctl [global options] start [options] [<name>]\ \ Where [options] are:\ \ -a Start all servers\ -t <type> Start only servers of specified type