TOC
How to Install WebGUI
Getting Started
Assumptions
- You are installing to /data/
- You are using FreeBSD 5.4 or greater as your host system
- You are installing WebGUI 7.0.7 or higher
- You are installing, or already using, MySQL 5.0
- You are installing, or already using, Apache 2.0
- You already have Perl 5.8.8 or greater installed
Other
- "webguiuser" is the example MySQL user
- "changeme" is the example MySQL password
- "example.com" will be used as the example domain
- All instances of 'IP_ADDRESS' should be changed to your server's external IP address
- Apache will be listening on 3 ports:
- 80: will forward to 443 (https)
- 443: https -- for secure browsing
- 81: For Spectre as it does not work with https nor with http due to the redirect
- This port should probably be firewalled so no one can access and/or have an Apache rule that only allows access to localhost.
Programs
Base Programs
WWW:
apache20 * mod_perl2 libapreq2 † * make WITH_PROXY_MODULES=YES install † If you get '/usr/bin/ld: cannot find -lexpat' when running 'make install' then do the following: ee /usr/ports/www/libapreq2/Makefile Look for "CONFIGURE_ARGS+= --with-apache2-apxs=${APXS}" and add the following to the end: --with-iconv=/usr/local/ --with-expat=/usr/local/ Save file and run 'make install'
Databases:
mysql50-server
Graphics:
ImageMagick
P5 Modules
WWW:
p5-libwww p5-libapreq2 p5-HTML-Template p5-HTML-Template-Expr p5-POE-Component-Client-HTTP p5-Apache-DBI * * make WITH_MODPERL2=yes install
Databases:
p5-DBD-mysql p5-Cache-Memcached
Archivers:
p5-Archive-Tar p5-Archive-Zip
Mail:
p5-Net-SMTP-Server
Devel:
p5-Tie-IxHash p5-Time-HiRes p5-Log-Log4perl p5-Date-Manip p5-Pod-Coverage p5-Test-MockObject p5-Test-Deep p5-DateTime p5-DateTime-Format-Strptime p5-DateTime-Format-Mail p5-POE p5-POE-Component-IKC p5-Data-Structure-Util p5-BSD-Resource
TextProc:
p5-XML-Simple p5-HTML-TagFilter p5-Pod-POM p5-Text-Autoformat
Net:
p5-SOAP-Lite p5-ResourcePool-Resource-Net-LDAP
Graphics:
p5-Image-Size p5-Image-Info
Converters:
p5-JSON
Finance:
p5-Finance-Quote
"CPAN":
CPAN * Tie::CPHash DateTime::Cron::Simple HTML::Highlight Template † Parse::PlainConfig XML::RSSLite Net::Subnets Color::Calc ‡ * (Upgrade to allow the -f option) † (Answer 'y' to first 2 dependencies, 'n' to 3rd) ‡ (answer "yes" to dependencies)
Command Line to Install All Programs
READ ALL FOOTNOTES ABOVE BEFORE USING THIS!
Be sure to check for an 'OK' after each Perl CPAN Module is installed when using the CPAN command lines given below.
cd /usr/ports/www/apache20 && make WITH_PROXY_MODULES=YES install && cd ../mod_perl2 && make install && cd ../libapreq2 && make install cd /usr/ports/databases/mysql50-server && make install cd /usr/ports/graphics/ImageMagick && make install cd /usr/ports/www/p5-libwww && make install && cd ../p5-libapreq2 && make install && cd ../p5-HTML-Template && make install && cd ../p5-HTML-Template-Expr && make install && cd ../p5-POE-Component-Client-HTTP && make install && cd ../p5-Apache-DBI && make WITH_MODPERL2=yes install cd /usr/ports/databases/p5-DBD-mysql50 && make install && cd ../p5-Cache-Memcached && make install cd /usr/ports/archivers/p5-Archive-Tar && make install && cd ../p5-Archive-Zip && make install cd /usr/ports/mail/p5-Net-SMTP-Server && make install cd /usr/ports/devel/p5-Tie-IxHash && make install && cd ../p5-Time-HiRes && make install && cd ../p5-Log-Log4perl && make install && cd ../p5-Date-Manip && make install && cd ../p5-Pod-Coverage && make install && cd ../p5-Test-MockObject && make install && cd ../p5-Test-Deep && make install && cd ../p5-DateTime && make install && cd ../p5-DateTime-Format-Strptime && make install && cd ../p5-DateTime-Format-Mail && make install && cd ../p5-POE && make install && cd ../p5-POE-Component-IKC && make install && cd ../p5-Data-Structure-Util && make install && cd ../p5-BSD-Resource && make install cd /usr/ports/textproc/p5-XML-Simple && make install && cd ../p5-HTML-TagFilter && make install && cd ../p5-Pod-POM && make install && cd ../p5-Text-Autoformat && make install cd /usr/ports/net/p5-SOAP-Lite && make install && cd ../p5-ResourcePool-Resource-Net-LDAP && make install cd /usr/ports/graphics/p5-Image-Size && make install && cd ../p5-Image-Info && make install cd /usr/ports/converters/p5-JSON && make install cd /usr/ports/finance/p5-Finance-Quote && make install cpan -i CPAN cpan -i Tie::CPHash cpan -i DateTime::Cron::Simple cpan -i HTML::Highlight cpan -fi Template cpan -i Parse::PlainConfig cpan -i XML::RSSLite cpan -i Net::Subnets cpan -i Color::Calc
Configuration
Apache
Comment out the following lines in /usr/local/etc/apache2/httpd.conf (if needed):
<IfDefine SSL> </IfDefine> ErrorLog /var/log/httpd-error.log CustomLog /var/log/httpd-access.log combined
Add a line similar to the following at the very bottom of /usr/local/etc/apache2/httpd.conf:
Include /data/apache-includes/default.conf
Put the following in /data/apache-includes/default.conf and edit as needed (you may want to play around with the max/min, etc servers):
#Some basic config LoadModule perl_module libexec/apache2/mod_perl.so LoadModule apreq_module libexec/apache2/mod_apreq2.so StartServers 5 MinSpareServers 5 MaxSpareServers 10 MaxClients 40 MaxRequestsPerChild 1000 DirectoryIndex index.html index.html index.php index.pl ServerSignature Off #PERL stuff for WebGUI PerlSetVar WebguiRoot /data/WebGUI PerlCleanupHandler Apache2::SizeLimit PerlRequire /data/WebGUI/sbin/preload.perl AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript <Directory /> AllowOverride None SetHandler perl-script Options +ExecCGI FollowSymLinks Order Deny,Allow Allow from all </Directory> Alias /extras /data/WebGUI/www/extras <Directory "/data/WebGUI/www/extras/"> Header set Cache-Control "max-age=36000" </Directory> #Default http port will be forwarded to https Listen IP_ADDRESS:80 #For SSL Listen IP_ADDRESS:443 #Only for Spectre should be firewalled or access denied to all but localhost Listen IP_ADDRESS:81 #For PHP AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps #SSL Stuff SSLRandomSeed startup builtin SSLRandomSeed connect builtin AddType application/x-x509-ca-cert .crt AddType application/x-pkcs7-crl .crl SSLPassPhraseDialog builtin SSLSessionCache dbm:/var/run/ssl_scache SSLSessionCacheTimeout 300 SSLMutex file:/var/run/ssl_mutex #Other Includes Include /data/apache-includes/example.com.conf
Put the following in /data/apache-includes/example.com.conf and edit as needed:
# Redirect any traffic coming into port 80 to SSL <VirtualHost *:80> ServerName example.com DocumentRoot /data/domains/dummy RewriteEngine on RewriteRule ^/(.*)$ https://example.com/$1 [R] </VirtualHost> # The main SSL web <VirtualHost *:443> ServerName example.com DocumentRoot /data/domains/example.com/public ServerAdmin admin@example.com SetHandler perl-script PerlInitHandler WebGUI PerlSetVar WebguiConfig example.com.conf PerlOptions +SetupEnv SSLEngine on SSLProtocol all SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+SSLv2:+EXP:+eNULL SSLCertificateKeyFile /data/certs/example.com.key SSLCertificateFile /data/certs/example.com.crt SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0 <FilesMatch "\.(cgi|shtml|phtml|php|php3?)$"> SSLOptions +StdEnvVars </FilesMatch> Alias /wiki /data/domains/example.com/wiki CustomLog /data/domains/example.com/logs/httpd-access.log combined ErrorLog /data/domains/example.com/logs/httpd-error.log </VirtualHost> # For Spectre only <VirtualHost *:81> ServerName example.com DocumentRoot /data/domains/example.com/public ServerAdmin admin@example.com SetHandler perl-script PerlInitHandler WebGUI PerlSetVar WebguiConfig example.com.conf PerlOptions +SetupEnv CustomLog /data/domains/example.com/logs/httpd-access.log combined ErrorLog /data/domains/example.com/logs/httpd-error.log </VirtualHost>
Create the "dummy" dir used for VHost:80:
mkdir -p /data/domains/dummy
WebGUI
Download the latest tar and untar to /data/
Spectre:
cd /data/WebGUI/etc && cp spectre.conf.original spectre.conf && ee spectre.conf
Edit the IP to match your server's IP and set port to '81'
Logs:
cd /data/WebGUI/etc && cp log.conf.original log.conf && ee log.conf
Edit "log4perl.appender.mainlog.filename" as needed
WebGUI Config:
cd /data/WebGUI/etc && cp WebGUI.conf.original example.com.conf && ee example.com.conf
Edit as needed making sure to at least edit the following lines:
"sitename" : [ "example.com", "www.example.com"], "dsn" : "DBI:mysql:example_com;host=localhost", "dbuser" : "webguiuser", "dbpass" : "changeme", "spectreSubnets" : [ "IP_ADDRESS/32" ], "spectreIp" : "IP_ADDRESS",
If you need a directory outside the WebGUI "realm" enable the following line and edit as needed:
# "passthruUrls" : ["/icons", "/documentation/pdf", "/my-custom-application", "/server-status", "/perl-status"],
MySQL
mysql -u root -p -e "create database example_com" mysql -u root -p -e "grant all privileges on example_com.* to webguiuser@localhost identified by 'changeme'" mysql -u root -p -e "flush privileges" mysql -u root -p example_com < /data/WebGUI/docs/create.sql
Server Start Scripts
The following is needed so the various services will start in the right order.
cd /usr/local/etc/rc.d mv mysql-server.sh 000.mysql-server.sh mv 000.apache2libs.sh 001.apache2libs.sh mv apache2.sh 002.apache2.sh
Create the Spectre start script:
ee 003.spectre.sh
Paste:
#!/bin/sh case "$1" in start) cd /data/WebGUI/sbin/ && perl spectre.pl --daemon ;; stop) cd /data/WebGUI/sbin/ && perl spectre.pl --shutdown ;; restart) cd /data/WebGUI/sbin/ && perl spectre.pl --shutdown && perl spectre.pl --daemon ;; *) echo "" echo "Usage: `basename $0` { start | stop | restart }" echo "" exit 64 ;; esac
Make script executable
chmod +xo 003.spectre.sh
Start the Servers
/usr/local/etc/rc.d/000.mysql-server.sh start /usr/local/etc/rc.d/002.apache2.sh start /usr/local/etc/rc.d/003.spectre.sh start
Check the various logs for errors.
Security Fixes
Disable the account username/login from showing on the profile page
Edit Profile.pm
ee /data/WebGUI/lib/WebGUI/Operation/Profile.pm
Look for the following which is on line 275 (in 7.0.7):
$vars->{displayTitle} = $i18n->get(347).' '.$u->username;
And change it to:
$vars->{displayTitle};
In the same file go to line 279 (in 7.0.7) and change:
.'. '.
To this:
.' '.
Notes
- If Apache PHP5 module is needed then the LoadModule line MUST come before the mod_apreq2 and mod_perl LoadModule lines
- If you want to customize the default WebGUI Apache error messages they are in /data/WebGUI/lib/WebGUI/Session/ErrorHandler.pm
- You will, in all likeliness, see "Segmentation fault (core dumped)" when starting Apache and see it on a regular basis in the Apache error logs. This is due to a problem with the ImageMagick Perl module. If you don't need any sort of images on your WebGUI site then you can skip the installation of ImageMagick which will fix this problem. Otherwise, other than it being quite the nuisance, it is nothing to worry about.