PhpWiki - FreeBSD

Introduction

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

Note: Non-SSL apache install.

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!
EDIT 22/07/2003: this is somewhat outdated now by the excellent webcp-httpd.php PHP httpd daemon. Yes, you read correctly, a PHP httpd daemon! This is still very much in beta but
EDIT 26/06/2005: "but" what? The sentence ends right there! Must be something missing here.

Commands executed as UID 0 in a csh shell, unless otherwise stated.

Download and Extract the web://cp tarball

Download the webcp tarball

Fetch the web://cp tarball from http://www.web-cp.net. At the time of writing the current version of web://cp is 0.5.6.

The current tarball can be obtained here: http://www.web-cp.net/releases/webcp-0.5.6.tar.gz

Visit http://www.web-cp.net/releases.php to get the latest!

To fetch the tarball directly from your shell:

root@users /root# cd /usr/local
root@users /usr/local# fetch http://www.web-cp.net/releases/webcp-0.5.6.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.6.tar.gz
webcp/
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 beast. 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. If your INSTALL file (like mine...) redirects you to the site, check this page:

http://www.web-cp.net/manual/index.php/RecommendedPermissions

But watch out! The instructions are for a Red Hat-like directory hierarchy. Please adapt it to FreeBSD. Looks like you only have to replace /home/webcp for /usr/local/webcp, but you SHOULD pay attention to this!

Modify the configuration files for web://cp

Copy the FreeBSD preconfigured config file into the existing config file. It will make things easyer for you. If you are wise, make a backup of the original file prior to overwritting it.

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

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

Note: the name of the file is config-freebsd.inc.php without the trailing "s" that prior versions had.

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.11.tar.bz2 http://uk.php.net/get/php-4.3.11.tar.bz2/from/this/mirror
<snip>
root@users /home/munk/php# tar zyvf php-4.3.11.tar.bz2 <snip>
root@users /home/munk/php# cd php-4.3.11
root@users /home/munk/php/php-4.3.11#

Note: The PHP Download page is located here: http://uk.php.net/downloads.php

Be sure to take the latest PHP 4 but NOT the PHP 5 stuff!

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-cli \
--disable-cgi \
--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 \
--enable-ftp \
--with-expat-dir=/usr/local \
--with-zlib=yes \
--prefix=/usr/local/webcp/php

Be sure to include de --enable-cli and --disable-cgi directives, they are REALLY important!

EDIT 26/06/2005: Actually, you have to issue the command without all those "\" and all in one single line.

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.11# mkdir /usr/local/webcp/php

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

root@users /home/munk/php/php-4.3.11# make
root@users /home/munk/php/php-4.3.11# 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 and the webcp-httpd.php scripts to reflect the path to the php CLI binary. Change the shebang line in /usr/local/webcp/server/webcp.php and /usr/local/webcp/server/webcp-httpd.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.11# 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: If you could not find them on your web://cp distribution, these files are available online:
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

If both scripts fail to start they will abort silently! To debug webcp.sh (and, incidentally, webcp.php), edit /usr/local/webcp/web/config.inc.php and raise the loglevel to 3:

$cfg['loglevel'] = 3;

After that, open another terminal and tail the webcp log file:

tail -f /var/log/webcp

This should give you a hint on what is wrong with the webcp.sh/webcp.php part of the problem.

Now to the webcp-httpd.sh/webcp-httpd.php burden. They don't log errors nowhere. (We don't need no education). Well, you should try to execute the server (webcp-httpd.php) without the webcp-httpd.sh script. If it works, there's a problem in the script and you will have to go through it. The script is pretty simple, though. If the server does not work it will complain about something and you will have your hint.

To start the webcp-httpd.php server without the script, just type in

cd /usr/local/webcp
php/bin/php -q server/webcp-httpd.php -d

and enjoy! Coke is it.

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 (e.g. 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!

This is a great moment! Take your time to celebrate your achievement.
You're sort of a hero if you managed to get this far.

See the online docs for help.
ererwe

Updated for 0.5.6 by Henry Cooper Avel (23.06.2005)
This tutorial: http://www.web-cp.net/manual/index.php/FreeBSD