Installing and Configuring web://cp on FreeBSD

Introduction

This is a short article covering the steps required to install and configure web://cp on FreeBSD.

These are only the steps I took to get web://cp working on my server at the time of writing. Since the code is still in beta, obviously this text has a very short shelf-life. YMMV.

Further, as is noted on the web://cp site, web://cp is not a trivial application to install and should not be attempted unless YOU UNDERSTAND EVERY COMMAND YOU EXECUTE AND THE IMPLICATIONS OF DOING SO.

As a generalized acid-test, if you have spent less than 1000 hours total time configuring apache, php, named, sendmail (or similar), writing php, administering mysql/postgresql (<add others here!>) - then you will have a hard time installing and configuring web://cp. If you have over 1000 hours total 'flight-time', you'll have a great time (in a masochistic kind of way:).
[EDIT 22/07/2003: this is actually not a joke, but if you have lots of enthusiasm and always RESEARCH YOUR PROBLEMS BEFORE ASKING FOR HELP, then you can probably half the above estimates and get along fine!]

Notes:

Download and Extract the web://cp tarball

Download the webcp tarball

Fetch the web://cp tarball from Uncle Felix's server. At the time of writing the current version of web://cp is 0.5.1.

The current tarball can be obtained here:
webcp-0.5.1.tar.gz

To fetch the tarball directly from your shell:

root@users /root# cd /usr/local root@users /usr/local# fetch webcp-0.5.1.tar.gz

Extract the web://cp tarball

The tarball will be extracted into it's own directory, /usr/local/webcp:

root@users /usr/local# tar zxvf webcp-0.5.1.tar.gzwebcp/ webcp/CVS/ webcp/CVS/Root <snip>

IMPORTANT NOTE ON GETTING THE LATEST VERSION OF WEBCP

At the time of writing, web://cp is a constantly evolving beaast. As such it is important that you update your source tarball to the latest version using the CVS repository. Details of the CVS repository can be found on the web://cp site.

Using CVS from a shell to checkout and track the webcp CVS source code is covered in Appendix A - Using CVS to track web://cp source

Add a webcp user to the system

WARNING - ensure uid 81 isn't already taken!

Execute the following command to add a 'webcp' user to the system:

pw adduser -n webcp -u 81 -d /usr/local/webcp -s /sbin/nologin

Ensure that the password field for webcp is set to '*' (use 'vipw'). This is an additional precaution in addition to setting the shell to /sbin/nologin to ensure illegal logins to the 'webcp' cannot occur.

Change permissions on /usr/local/webcp

In general, follow the instructions in the INSTALL file regarding permissions.

Modify the configuration files for web://cp

cp /usr/local/webcp/web/config-freebsd.inc.phps /usr/local/webcp/web/config.inc.php

and make any changes to /usr/local/webcp/web/config.inc.php to suit your server.

Note: this file is available here:

config-freebsd.inc.phps

Configure apache for web://cp

To recognize the new sites that web://cp adds to the system, the main apache configuration file - httpd.conf - must be configured to include the file /usr/local/webcp/httpd/include/include.httpd.

Add a line at the end of your main apache httpd.conf file /usr/local/etc/apache/httpd.conf to include the webcp httpd include config:

Include /usr/local/webcp/httpd/include/include.httpd

This will allow the regular httpd to include vhosts added by webcp.

Installing the PHP Command-LIne (CLI) binary for web://cp

The web://cp backend server - server/webcp.php - and the web://cp httpd server - server/webcp-httpd.php - both require that PHP be built as a CLI binary with various options so it can control/manipulate system processes. Rather than attempt to build and install this binary with these special options into the system proper - which might disrupt or modify an existing installation of PHP - instead we build the PHP CLI binary from the source PHP tarball and install it into /usr/local/webcp/php.

In the instructions below you will need to adjust your commands to obtain the latest current stable source release.

Obtaining and Extracting the PHP source tarball

Download the PHP source tarball into a temporary location away from the webcp folder. The best thing to do is create a subdirectory in your home directory called 'php' and download/extract the source to there:

root@users /home/munk# mkdir php root@users /home/munk# cd php root@users /home/munk/php# fetch -o php-4.3.2.tar.bz2 http://uk.php.net/get/php-4.3.2.tar.bz2/from/this/mirror <snip> root@users /home/munk/php# tar zyvf php-4.3.2.tar.bz2 <snip> root@users /home/munk/php# cd php-4.3.2 root@users /home/munk/php/php-4.3.2#

Note:
The PHP Download page is located here:
PHP Download Page

Building and Installing the PHP CLI binary

From the shell in the base directory of the tarball distribution we extracted above, execute the following 'configure' command line:

./configure \ --enable-versioning \ --enable-memory-limit \ --with-layout=GNU \ --with-zlib-dir=/usr \ --disable-all \ --enable-discard-path \ --enable-ctype \ --with-mysql=/usr/local \ --enable-pcntl \ --with-pcre-regex=yes \ --enable-posix \ --enable-session \ --enable-sockets \ --enable-tokenizer \ --enable-xml \ --with-expat-dir=/usr/local \ --with-zlib=yes \ --prefix=/usr/local/webcp/php

This will configure PHP with options suitable for web://cp.

Next, create a directory to install PHP into:

root@users /home/munk/php/php-4.3.2# mkdir /usr/local/webcp/php

Finally, build and install PHP by issuing the following command:

root@users /home/munk/php/php-4.3.2# make root@users /home/munk/php/php-4.3.2# make install-cli

This will install a directory tree under /usr/local/webcp/php containing the standalone php cli binary that will be used for the web://cp backend servers.

Modify the webcp.php script to reflect the path to the php CLI binary

Change the shebang line in /usr/local/webcp/server/webcp.php to:

#!/usr/local/webcp/php/bin/php -q

Copy the webcp.sh rc init script into /usr/local/etc/rc.d

To ensure the web://cp backend server - server/webcp.php - and the web://cp httpd server - server/webcp-httpd.php - both start when your system boots, copy and make executable the rc init scripts located in /usr/local/webcp/contrib/freebsd:

root@users /home/munk/php/php-4.3.2# cd /usr/local/etc/rc.d root@users /usr/local/etc/rc.d# cp /usr/local/webcp/contrib/freebsd/webcp.sh ./ root@users /usr/local/etc/rc.d# cp /usr/local/webcp/contrib/freebsd/webcp-httpd.sh ./ root@users /usr/local/etc/rc.d# chmod +x webcp.sh webcp-httpd.sh

Note:
These files are available online here:
http://munk.nu/webcp/webcp.sh
http://munk.nu/webcp/webcp-httpd.sh

Start the webcp.php backend server

To save rebooting, start the web://cp servers from the command line:

root@users /usr/local/webcp/server# /usr/local/etc/rc.d/webcp.sh start root@users /usr/local/webcp/server# /usr/local/etc/rc.d/webcp-httpd.sh start

Creating an initial web://cp reseller account

Finally, in a browser browse to the $cfg["sysname"]:$cfg["port"] location you specified in your web://cp configuration file - ie http://example.com:81/ where you will be prompted to complete a form to create the initial web://cp user.

After clicking submit you will be told that new accounts/domains have been created and you can login to your webcp panel for the first time! See the online docs for help.

Appendix A - Using CVS to track web://cp source

Set your $CVSROOT environment variable

cvs is commonly available by default on most flavours of Unix - certainly those flavours currently supported by web://cp. Before using cvs to manipulate the webcp CVS repository it is best to set your $CVSROOT shell environment variable. This will save you a lot of typing when using cvs.

root@users /usr/local/webcp# setenv CVSROOT :pserver:nobody@webcp-devel.can-host.com:2401/var/lib/cvsroot

With the $CVSROOT variable set in your shell, you do not have to type:

-d :pserver:nobody@webcp-devel.can-host.com:2401/var/lib/cvsroot

when issuing the cvs commands below.

Logging into CVS

With $CVSROOT set as above, logging into the webcp CVS repository is as easy as:

root@users /usr/local/webcp# cvs login Logging in to :pserver:nobody@webcp-devel.can-host.com:2401/var/lib/cvsroot CVS password: <hit enter here>

Note in the above that no password is required for access to the webcp CVS repository as the 'nobody' user.

Checking out the latest version of the web://cp source from CVS

To obtain a local copy of the web://cp source from the CVS repository, issue the cvs 'checkout' command, followed by the module name 'webcp'.

This will create a directory called 'webcp' in your current working directory and populate that directory with the latest version of the web://cp source files from the CVS repository. A good tip here is to create a 'cvs' directory in your regular user's directory, change to that directory and then issue the checkout command:

root@users /usr/local/webcp# cd /home/munk root@users /home/munk# mkdir cvs root@users /home/munk# cd cvs root@users /home/munk/cvs# cvs checkout webcp <snip>

In this way you can easily track differences between your 'production' code and the version currently up to date in CVS.

Keeping up to date with CVS updates

Subscribing on the web://cp forum for CVS update notification

Updates to the web://cp repository are made regularly. To keep abreast of the latest changes to the CVS repository you can ask to be added to the CVS mailing list:

Once added - courtesy of Felix - you will receive notification by email whenever the CVS repository is updated.

Updating your local copy of the CVS source files using cvs

To update your copy of the source files to the latest version in the CVS repository, change into the directory containing your local version of the source files and issue the cvs 'update' command:

root@users /home/munk/cvs# cd webcp root@users /home/munk/cvs/webcp# cvs update

A Warning about cvs update - and a nice intro to the cvs status command

cvs update involves checking every single file in the repository against your locally stored version information and can take some time if you are on a slow connection. With this in mind you can use the cvs 'status' command to check if any files need updating:

root@users /home/munk/cvs/webcp# cvs status <snip> File: FEATURES Status: Up-to-date Working revision: 1.2 Repository revision: 1.2 /var/lib/cvsroot/webcp/FEATURES,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) =================================================================== File: HELP Status: Up-to-date <snip> cvs server: server/lib/linux-domain.wcp.phps is no longer in the repository <snip> =================================================================== File: domain.wcp.phps Status: Needs Patch Working revision: 1.1 Repository revision: 1.3 /var/lib/cvsroot/webcp/server/lib/domain.wcp.phps,v Sticky Tag: (none) Sticky Date: (none) Sticky Options: (none) ===================================================================

From the snippet above we can note several things:

Another cvs update warning - and a nice intro to the cvs diff command

cvs update can modify your files in a way that is hard to undo easily. With this in mind it can be prudent to first check exactly what changes have been made since your last update. To do this, use the cvs 'diff' command:

root@users /usr/local/webcp# cd server/lib/ root@users /usr/local/webcp/server/lib# cvs diff freebsd-user.wcp.phps Index: freebsd-user.wcp.phps =================================================================== RCS file: /var/lib/cvsroot/webcp/server/lib/Attic/freebsd-user.wcp.phps,v retrieving revision 1.1 diff -r1.1 freebsd-user.wcp.phps <snip>

This command allows you to see exactly what changes have been made to the file you execute the cvs 'diff' command on. Note if you execute cvs 'diff' without a file argument, cvs will find diffs for every file in the current directory hierarchy - which can take a long time!

Valid XHTML 1.0!