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!]
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
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>
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
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.
In general, follow the instructions in the INSTALL file regarding permissions.
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:
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.
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.
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
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.
Change the shebang line in /usr/local/webcp/server/webcp.php to:
#!/usr/local/webcp/php/bin/php -q
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
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
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.
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.
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.
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.
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.
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
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:
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!