Written RackForms Installation Guide

Before you install RackForms, please read and understand the End User License Agreement.

IMPORTANT - Yes this is a long document, but please understand this doesn't mean the install process is complicated! If you'd like to watch a video instead, please use this link.

RackForms is an advanced piece of software, and by its very nature performs many advanced functions many other applications simply do not. Every step has been taken to ensure RackForms runs great on a vast array of servers, and yours will almost certainly be no exception.

That said, the more time you take now on making sure you know all the in's and out's the software, the easier you installation process will be, and if something does come up in the future, the better prepared you'll be to manage such issues. That said, if you simply want to skip ahead to the install field descriptions, feel free!

The good news:

All told there are only a few fields that need to be set, in many cases installation will only take a few minutes.

For example, if you already have a database and database user name and password set on a GoDaddy server, the installation process will only take around 3 minutes.

If you have a dedicated server and need to create a database and set file permissions, installation will usually take around 5 minutes.

Their are times however, when we're new to our web hosting management console and installation will take longer, generally around 30 minutes to an hour. The key here is not so much the RackForms bits, but simply learning to navigate a complex hosting system.

The Installation Process

GoDaddy Users Please Read!	cPanel Users Please Read!
If you are a GoDaddy + Windows customer we have created a special install section just for you! We also have a special help page specifically on GoDaddy database setup.	cPanel is a popular administraiton tool used by a majority of web hosting providers on the market today. cPanel makes installing RackForms easy, though it does have a few quirks that our cPanel install help page will help you blast though!

General Installation Help Video
You may want to watch this install help video. We cover a basic installation, as well as have some fun 'breaking' the install process by recreating common problems such as database permission errors, then show you how to fix said problems.

Highly recommended as as substitute or compliment to the printed instructions below.

Looking to Upgrade RackForms Versions: This video will help!

It is advisable to set aside at least 1 hour for the installation process. Many users will find the process takes significantly less time, others longer.

If you come across a heading that doesn't pertain to your set up, such as Microsoft SQL Server when you're running MySQL, you can always safely skip that part.

Most of all, be patient and have fun!

Free Direct Installation Help
We web developers are busy people, and the sheer number of server configurations and SQL setups can present special challenges for an advanced application like RackForms. That's why we offer Free Setup and installation assistance for users who find themselves at an impasse when trying to install their software. It should be noted that this is a last resort, as we place your server security and PCI regulations ahead of all else. In some situations though, you simply want to have the software installed and move on to more important things!

If you want to have us install the software for you, we will need access to your cPanel or other server management software. We will also need access to your Database server in the form of user and password. Collect this information, and send an email to support@rackforms.com.

The only other requirement we have is that you place the extracted rackforms.zip file contents on to your web server, this way we can skip some FTP steps if possible for faster service.

Getting Down To Business

There are a few considerations to make when installing RackForms for the first time. In this section then we'll cover a few of the basics, and also cover important items that may arise during the install process. Please note for most users this is simply a checklist of sorts if you run into issues down the road. That is to say, most web hosting providers will not have any of the items listed below as potential road-blocks.

If we do run into issues though, this is a great place to remember to head back to for further help. For now it's suggested to skim through this material as it's always good to have a solid understanding of the items being discussed!

PHP System Requirements

RackForms Requires a Web Server running PHP 5.1.4 or higher. Running the latest stable version is advisable. No branch of PHP 4 is supported, as RackForms uses Object Oriented Features specific to PHP 5.

RackForms and open_ssl
The RackForms licensing process requires a connection to our secure server. In very rare instances, your server may not have open_ssl support enabled. The installer will alert us if this is the case. If so, we will need to enable open_ssl support, the details of which will depend on your hosting setup. In general, Windows users simply need to uncomment the extension=php_openssl.dll line in your php.ini file. Linux users may need to recompile php.

RackForms and magic_quotes_gpc
RackForms does not support servers where so called Magic Quotes are enabled. Most every hosting company already has this feature disabled by default, so no further action is needed. Most importantly, as of PHP 5.3 this feature is depreciated, and starting with PHP 6, will be removed entirely.

A simple check of your php config for the text magic_quotes_gpc will determine of you have this feature on. You can view your php config file by clicking the "PHP Info" link at the top of the RackForms Editor and Installer.

If it is "on", most hosting companies allow access to an .htaccess file, this file, generally at the root of your web server’s public_html directory (or if it doesn't exist already, would be created their), allows you to set text strings which control you PHP setup.

In the case of magic_quotes, we would set:

magic_quotes_gpc = off

To disable the feature.

RackForms and Suhosin
Some servers will come pre-configured with the Suhosin patch, which is part of the Hardedned PHP Project. RackForms works just fine with this patch with one main exception: the default value of the: suhosin.request.max_value_length setting will restrict your forms to around 40 fields. To fix this you will need to up this limit. Please check with your hosting company to find out how to change this value.

Register Globals
RackForms does not support servers that have register_globals enabled. As this is a depreciated feature in PHP 5 this will almost never be an issue, but if your server has this enabled, you will want to disable it in the php.ini via:

register_globals = Off

open_basedir (SAFE MODE Restriction in effect errors)
As part of its normal operations RackForms includes several files within each job folder, but not outside of this job folder unless you create your own includes. Thus, RackForms will not work properly with an incorrect setting for open_basedir, in that should you restrict open_basedir to a /tmp folder or similar, RackForms will not be able to include these important files.

The best solution for most users then is to simply not set open_basedir, as unless you allow others to host files within your user space you are always in total control over your sites source code and by extension, who has access to run and modify code.

If you absolutely must set this value, then you will at minimum need to set the base of your RackForms folder to be an allowed location.

GoDaddy Preview DNS Note: The RackForms editor will not work if your site is using the GoDaddy Preview DNS feature due to a conflict in the JavaScript code the previewdns.com site uses. To use RackForms make sure your site is being hosted normally.

Output Buffering

RackForms generally requires the server we install to has output_buffering enabled. If we receive a warming message about this being disabled, we generally follow these steps to enable:

1. In the installer we want to click the PHP Info link:

2. Search for the word .ini

3. When found, locate and open that file with a text editor of your choice.

3. Search for the text buffer

4. When we find the text output_buffering = place the word On or 1 after the = as in:

5. Restart the web server.

Database Layer

RackForms makes extensive use of a database layer to handle form jobs, submissions, and user management. Three major Database vendors are supported: MySQL, Microsoft SQL Server, and PostgreSQL. For MySQL you must be running MySQL 5 or higher, for SQL Server you'll need Server 2005 or higher, and PostgreSQL requires version 9 or higher.

Please note that like the rest of this document this section is thorough but not even required reading for most users. That is, to install RackForms all we need is a database it can write its tables to and along with that, a valid database user name and password.

So long as we have that we can think of this section as more of a trouble-shooting destination than anything else.

MySQL Extension
For MySQL users you can choose between PDO or MySQLi:

PDO - RackForms requires the PHP_PDO, which on Windows is a bundled .dll from version 5.1.0 and up, and on Linux as a PECL extension from version 5.0.3 and up.

You will also need to enable the specific PDO driver in php.ini for your database. For example, with MySQL on Windows the extension is php_pdo_mysql.dll.

MySQLi - Almost all web hosts will provide the MySQli extension, and is generally considered one of the most common extensions.

MySQL Database Privileges
By default RackForms uses prepared statement queries for all MySQL database interaction. This means RackForms should be compatible with all versions of MySQL 4 and above (though 5 is the only officially supported database).

However, RackForms also supports MySQL Stored Procedures. If you choose to use Stored Procedures, it is vital for MySQL users to assign the proper privileges to the RackForms user. Specifically, you must GRANT the RackForms database user:

• CREATE ROUTINE
• ALTER ROUTINE
• EXECUTE

Further, if you are running MySQL in a replicated or binary logging environment, you may need to assign special privileges to the RackForms user, or set the log_bin_trust_function_creators system variable to 1.

Keep in mind these extra permissions are only necessary if you check the 'Use Stored Procedures' box. RackForms will run the exact same if you choose to use procedures or not. That is, all feature and functionality between the two modes is identical.

MySQL User Permission Settings
When we create the RackForms database it's also a good idea to create a new user for this database as well. This is not strictly needed of course, but is something to consider for maximum security.

If we do create a new user, or the user hasn't been used for any other purpose, please be sure to set the database user permissions correctly. Generally speaking we want to make sure the user has the basic, SELECT, INSERT, UPDATE, and DELETE permissions for the RackForms database.

This attention to permissions is particularly true if our database management tool specifies a wildcard host (%) for the user by default.

In some local server instances using wild cards is accepted, but in most cases we need to explicitly set 'username' @ 'localhost'. That is, the host name for the user must be at minimum, localhost.

max_allowed_packet
Default installations of MySQL are limited to 1MB per-packet. In many instances this is fine, but because RackForms allows you to save any and all file uploads to the Database (as well as save very large jobs with hundreds of fields), you will run into problems if you try saving elements or jobs to the database that are at or near this limit. There is a simple solution however, and that is to raise the default limit to something larger. The maximum packet size is 1GB so you have plenty of room to experiment.

Please keep in mind this limit is only an issue if you plan on using RackForms in a manner that allows for uploads larger than 1MB or again, very large jobs (think 400 fields or more). The RackForms installation process will not run into this limit at any time, so you do not need to worry about this limit if you plan on simply installing the software and never allowing file uploads larger than 1MB.

One important point before the next topic -- generally speaking RackForms jobs larger than 20 or so pages will start to run into issues with this setting as well. Thus, if you have very large jobs you'll want to keep this setting in mind if your jobs start refusing to save.

MySQL Character Sets and Collation
RackForms uses the UTF-8 Character Set with utf8_general_ci collation for all database calls. Thus, you will need to make sure the database you create or use with the RackForms installation uses these settings or you will run into subtle problems with character encoding or outright installation errors.

Of the two issues that can arise by not having proper settings, the most serious, and ultimately one that can halt an installation or user login, is an improper collation setting. Although your Database management tool will have its own specific procedure for setting collation, at the most basic level you can issue a simple sql statement to set the character set and collation for the RackForms database to utf8/utf8_general_ci.

For example: ALTER DATABASE your_RackForms_database_name CHARACTER SET `utf8` COLLATE `utf8_general_ci`

If you have phpMyAdmin, you can select your database, click the Operations tab, then select the proper collation (utf8_general_ci) from the drop down list 'Collation:' near the bottom of the page.

Again, all database management tools will have varying procedures for setting character set and collation, but the process is very simple in almost all cases.

More on MySQL character set support and Character Sets and Collations in General.

MySQL / MSSQL and Escape Characters via NO_BACKSLASH_ESCAPES
Because RackForms makes heavy use of custom code segments, you may find yourself in a situation where you want to create a PHP code segment like:

<?php
$var = 'This is a testing server\'s dream';
?>

That is, creating a string that escapes upon itself. The problem is most MySQL servers treat back slashes as escape characters, which means your code would have the escaping slash stripped, leading to a PHP error when the page is run. This happens because all job information is always saved to the RackForms database, and when this PHP code is INSERTED into the database, the slash will be striped if not first escaped. More on MySQL Escape Characters.

Starting with Build 611 RackForms has added an app/config.php option to allow for both modes, that is, your server is or is not running with NO_BACKSLASH_ESCAPES mode.

To find what mode your server is running in, launch a MySQL management tool such as phpMyAdmin and look for the sql_mode listing, which can be found in phpMyAdmin under the Variables tab. If your server is in NO_BACKSLASH_ESCAPES you will see something similar to:

NO_BACKSLASH_ESCAPES,STRICT_TRANS_TABLES [etc]

If you see this, you will want to open your app/config.php file and set the NO_BACKSLASH_ESCAPES line to read:

define('NO_BACKSLASH_ESCAPES', '1');

This will make sure that RackForms does not try to escape your code segments, which means they will run as expected on a live page.

Please note that MSSQL servers will run with NO_BACKSLASH_ESCAPES mode ON (1) by default.

MySQLi and Network Solutions Hosting
It appears that some Network Solutions hosting accounts may be affected by a bug in PHP and the MySQLi extension. Specifically, after installation and trying to login we may get an error like:

1210: Incorrect arguments to mysql_stmt_execute

It should be noted that we will only get this error if our app/config.php has the debug line:

define('DEBUG', '0');

set to:

define('DEBUG', '1');

If our debug line is not set to 1 we will usually just get a blank white page. If eiether of these issues is the case and we're on Network Solutions Hosting, we will need to reinstall RackForms and use the PDO driver option via this drop box.

Confirmed hosting account with this issue as of July 28th 2011 are ones running PHP version: 5.2.17.

Microsoft SQL Server
For Windows users of SQL Server you'll need to mnually download and install the official Microsoft SQL Server Driver for PHP, or use the much easier Microsoft Web Platform Installer.

Please note RackForms only supports SQL Server Authentication, not integrated Windows auth.

If using the mnual method, installation means extracting a .dll file into your php extensions directory and adding a line to your php .ini file:

extension=php_sqlsrv_ts.dll

Restart your web server and the extension is ready to go. Please note this driver is for Windows only. If you want to run Linux, you must use MySQL as your database layer.

MSSQL connectivity also requires the SQL Server Native Client (x86 or 64bit) to be installed on the Machine PHP runs on. This is usually installed by default when you install the server components.

More on SQL Server 2005/08 Driver for PHP requirements here.

More information on programming for the the SQL Server Driver for PHP can be found here.

The offical forum for the SQL Server Driver for PHP can be found here.

Microsoft SQL Server Hints
a) When we install SQL Server, be it a full version or Express, you may want to install the SQL Server Management Studio application. A snag I've run into is when we first launch the application the connection parameters correctly identify the Server Name property, but leave out the all important Computer Name component.

So for example, if you install the Express version the default instance name of SQLExpress will be set, but we must add our computer name to this login property. My computer name, for example, is Matt-PC, so in the Server Name box I user the full value of:

MATT-PC\SQLExpress

b) Another handy hint is when we install SQL Server I like to enable Mixed Mode Authentication, especially if on a development machine. Problem is, while the installer lets us set the password, it never tells us the name of this account.

The name of this default account is sa.

c) It appears Server 2008 may not support file uploads out of the box. Should you run into any issue with file uploads or the install process, we'll want to open the SQL Server Configuration Manager Application (usually located in the Start Menu) under:

Microsoft SQL Server 200x > Configuration Tools > SQL Server Configuration Manager

We'll then click the SQL Server Services item in the left pane, then double-click the SQL Server item in the right pane.

In the window that pops up click the FILESTREAM tab and check all boxes. Now restart the server.

MSSQL And Database Collation

RackForms requires your MSSQL server be running a case-insensitive collation, such as SQL_Latin1_General_CP1_CI_AS.

Running a case-sensitive collation is not supported, and will lead to unexpected errors.

https://www.microsoft.com/web/downloads/platform.aspx

PostgreSQL

PostgreSQL users need to have the pgsql database driver extension installed.

PostgreSQL is unique among database in that instead of the database holding tables, an entity called a 'schema' does. Further, each database in your PostgreSQL installation can have multiple schema, and each database contains a default schema called 'public'. This means in theory, software like RackForms could install to a schema within a specified database.

At this time however, we do not support installing or running RackForms on any schema except 'public'. Thus, when we install RackForms to a database, its tables and data is installed to the 'public' schema.

File Permissions - External Files and Web Server Access

We must have the ability to write files to your web server and to change permissions if necessary to allow your web server to write such files. You should also be careful of assigning too high a privilege level to your directories and files, as not only is it insecure, but some web hosting providers will automatically prevent your pages from loading as a security measure.

For example, if you assign 777 to your /output directory this location is now world-writeable, and any forms you create may not load properly as a security precaution. This error would manifest itself when you build and export a form as an 'Internal Server Error' page instead of your form page.

For best results, follow the permission guidelines below:

- UNIX Systems
755 or 775 to the /ouput directory and all sub-directories of /output
644 to the config.php files located in /app/config.php and /app/movefiles/config.php

Note that using 755 or 775 on the /ouput directory will depend on how you have your web server setup. In most cases, your web server will run as its own user and group (generally apache), which means you could: chgrp -R apache /output, which would mean a chmod -R 755 /output would allow the apache user to write to the /output directory, which is what we want.

Again, as stated above, it is generally not advisable to use: chmod -R 777 /output.

The general rule of thumb is start with the lowest level of permissions and work up.

SE Linux

Some Linux systems, in particular centOS, ship with a security layer called SE Linux. If not properly configured this system will prevent Apache from writing files to the file system, an important and nessesary part of the RackForms form creation process.

To fix this, follow the general guidelines here.

# semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/rackforms/output(/.*)?"
# semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/rackforms/app/config.php(/.*)?"
# semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/rackforms/app/movefiles/config.php(/.*)
          

Replace the path parts with your specific values.

- Windows Systems
You should provide your web server user (IUSR on IIS 7, or IUSR_MachineName on IIS6) with read/write permissions to the /output directory and all sub-directories of /output, and write permissions to both config.php filesas detailed above.

It's important to note that if possible, always set and check file security settings in your hosting providers native file manager, not an FTP program. Such FTP programs, be it Dreamweaver's built-in system, Filezilla, or anything else, can be notoriously unreliable and sometimes outright unsupported.

RackForms and Apache mod_security
Some hosting companies use Apache's mod_security module. While this module can be helpful for some scenarios, an improperly configured mod_security module will end up preventing RackForms from creating forms.

If this is the case your server will usually exhibit a behavior where RackForms will install correctly but not be able to create forms.

If this happens mod_security has been improperly setup and needs to be modified or disabled to use RackForms. Your web hosting provider should be able to help with this issue if it arises.

Of course it should be noted this is similar to file permissions issue, though one important difference should be noted: when file permissions are the issue RackForms will usually not install. However, if it does install when we save a form the RackForms/output/forms folder will not get any new content saved to it.

In contrast, a mod_security issue usually manifests itself in that a job folder will be created and several .html, .js, and .css files placed into it, but no .php files are created. Again, should this be the case please feel free to contact us or contact your host and check with them to see if mod_security is enabled.

RackForms and Apache mod_rewrite
Because RackForms makes extensive use of file creation and manipulation, we need to make sure we do not have any stray rewrite rules that conflict with PHP's own pathing logic. Admittedly this is rare, but I have recently seen just such a case with this rule:

RewriteRule (.*) check.php?where=$1&%{QUERY_STRING} [L]

In short, if you have strange or unexplained issues with file permissions, or problems with automatic redirection (say when you try to load the install.php page), check your rewrite rules and disable as needed!

Email Authentication Settings
In some cases your server may not work with PHP's mail() function and by extension, the default mail delivery method of RackForms. This can happen if your server needs to use authenticated email relays, or your running a "consumer" Windows box with no SMTP server installed (e.g. Vista). There are three possible solutions for this:

Solution 1 - If you do have an MTA and thus have access to a mail agent, you can set your MTA to allow for emails that originate within the same domain to be sent without authentication. As part of this solution you need to edit your php.ini file to provide information on your SMTP host in the following manner:

[mail function]
; For Win32 only.
SMTP = smtp.your_host.com
smtp_port = 25

For Win32 only.
sendmail_from = me@example.com

This solution will generally not apply to shared hosting environments, that is, a server you do not administer. On a final note, smtp_port may not be 25, but a different value such as 587.

Solution 2 - If you are running in a shared hosting environment or otherwise one that you cannot enable same domain authentication pass through, you can try using the Simple Email and Email+ module's Additional Command Line Parameters options box to pass the MTA switches that would enable mail(). This is not practical for most servers, so the last option will probably be the best...

Solution 3 - Use RackForms SMTP. Starting with build 623 RackForms now supports SMTP authentication for sending email. To send authenticated mail, you would enable SMTP email for a Simple Email or Email+ item and fill in the proper email authentication details. SMTP email allows you great latitude--for example, many free email services such as Google's Gmail support SMTP email, which means you could send mail via RackForms on a local Vista box, which is great for development and testing.

Flash File Uploads and Apache Server Security
RackForms uses an Adobe Flash based file upload system. In some cases your Apache web server may be configured to block such uploads. If you run into a problem where images you attempt to upload are not being displayed on in your forms, follow this process to remedy the problem:

Using a file management tool, create a file on the root of your public_html or domain folder called:

.htaccess

You may already have one, if that is the case, simply open it for editing.

Add to the .htaccess file the following text:

<IfModule mod_security.c>
SecFilterEngine Off
SecFilterScanPOST Off
</IfModule>

Save and close the .htaccess file. You should now be able to upload images.

General Directory Permission Settings (UNIX Servers Only)
Starting with build 624 their is a new configuration option for setting folder and file permissions for every object created by RackForms. You will find these options in two places:

RackForms/app/config.php

RackForms/app/movefiles/config.php

In both files the actual code for these settings looks like:

// Build 624 - Set Write Permission Level - Not Needed On Windows
define('DIRECTORY_MOD', 0755); // Octal based UNIX permission level e.g. 0755, 0777

// Build 624 - Set File Write Permission Level - Not Needed On Windows
define('FILE_MOD', 0644); // Octal based UNIX permission level e.g. 0644, 0664

Thus, by default RackForms will use 0755 for folders and 0644 for files. This should work for just about every server in existence. However, if you need to adjust these permissions, you certainly can.

Requirements Summary
To summarize the last three sections, you'll need PHP 5.1.4 or higher, MySQL 5.0 or Microsoft SQL Server 2005 or greater, and the ability for your web server to write files to specific locations in your RackForms installation directory.

The RackForms Installer Screen

Mouse over and click a letter to jump to the explanation for that item.

By default the RackForms application comes with an installer script: install.php, located at the root of the RackForms directory. This file will load automatically if you try to run RackForms with this file present.

The installer requires two sets of information to complete its task, Database and User information.

The section below is simply an explanation of each field for those two categories of information. If you're an experienced web developer, many of these fields will be familiar. If they are, feel free to fill them out and hit install. In most cases everything will simply work and the install process will be complete. If you run into problems, or simply want to know as much as you can, the section below should be able to answer many of your most common questions.

Database Information (Please see the image above and below for locations of the lettered elements):

•  A  Database Vendor - Choose between MySQL, MSSQL and PostgreSQL.
  
  If you choose MySQL, you can select between the MySQLi extension or PDO. Generally speaking their isn't a difference between the two, though you will probably want to select the one you use for any custom database work for consistencies sake. However, one important consideration as of this writing (Build 680), is if you plan to use LIKE search terms in Builder forms you must select PDO. Thus it may be adviseable, if you have both drivers, to use PDO, though again, this only matters if you plan on creating Builder forms where you allow users the ability to search for data using the LIKE SQL operator.
  
  Back to Install Screen Image

•  A-1  Perform Clean Install - By checking this box you will perform a clean install, which means all RackForms tables will be deleted and then recreated. This option only has an effect if you have an existing installation where tables have already been created. Be aware that removing all RackForms tables will effectively delete any RackForms data such as saved jobs, entries, and user accounts.
  
  Back to Install Screen Image

•  A-3  Use Stored Procedures - The usage of this box depends on what Database Vendor you have selected:
  
  MySQL - If you know your MySQL web hosting provider supports stored procedures (GoDaddy for example), you can safely check this box. RackForms will then use stored procedures for most database connectivity. However, not all hosting providers enable or even allow the use of stored procedures (HostGator for example), so you may simply want to leave this unchecked. Stored Procedures are by no means required, and the application will act no different without procedures.
  
  MSSQL - If you're using Microsoft SQL Server, you must check this box. You will notice the box is checked automatically if you select MSSQL from the Database Vendor box.
  
  Back to Install Screen Image

•  B  Database Name - The database schema you want RackForms installed too. Please note the installer will not over-write existing database tables that are not RackForms related. All RackForms tables are prefixed with fb_.
  
  Please note: This Database must already exists for the install process to be successful!
  
  cPanel Shared Hosting Users Please Note: cPanel has a habit of appending your UNIX user name to the value used as the database name. For example, if you type in formbos as the database name and your home directory value is: /home/test, cPanel will actually create a database called: test_formbos.
  
  The reason why I tag this as strange is because when creating the database name cPanel never actually tells you this is happening, it just does it. The good news is that after you crate the database you will start to see it show up in the new format, but for first time users you may miss this!
  
  Back to Install Screen Image

•  C  Database User Name - In MySQL this is fairly strait forward, just find your database user name. In MSSQL you'll need to make sure you're server is running in 'SQL Server and Windows Authentication Mode', which is accessible in 'Server Properties' (right click on the database instance in the Object Explorer in SQL Server Studio). RackForms does not use Windows Authentication for SQL Server connections, hence the need for SQL Server Authentication. Please note this setting is not set by default with a fresh SQL Server installation, be it in the Enterprise or Express editions.
  
  cPanel Shared Hosting Users Please Note: cPanel has a habit of appending your UNIX account name to the value used as the user name. For example, if you type in formbos as the user name and your home directory value is: /home/test, cPanel will actually create a user called: test_formbos.
  
  The reason why I tag this as strange is because when creating the user name cPanel never actually tells you this is happening, it just does it. The good news is that after you crate the user you will start to see it show up in the new format, but for first time users you may miss this!
  
  Back to Install Screen Image

•  D  Database Password - The password for your RackForms database user.
  
  Back to Install Screen Image
  

•  D-1  Database Port - (MySQL AND POSTGRESQL ONLY, NOT REQUIRED) - Most MySQL installations use port 3306, which means you can generally leave this field as set as that is considered a default port and used automatically. However, some stacks such a MAMP will use port 8889 by default, in other circumstances your server administrator may have used a different port for security reasons. If you are using a port number other than 3306, place it in this field.
  
  Most PostgreSQL users will need to manually enter the default of 5432.
  
  Back to Install Screen Image

•  D-2  MySQL Socket Path - (MySQL ONLY, NOT REQUIRED BUT GENERALLY NEEDED) - In many instances your web hosting provider my have configured MySQL in a way that changes where the default MySQL socket file is, and this change may cause the PDO or MySQLi extensions which RackForms relies on to fail.
  
  This can be a trickey value to set properly, so by default RackForms will inspect your server and attempt to set his value for you. However, if you receive connection errors despite being absolutely sure the database user name, password, database name, and host is correct, you should try using one of the other values from the drop down menu directlly below this field. If none of those values work you can also try:
  
  /var/run/mysqld/mysqld.sock
  
  /tmp/mysql.sock
  
  /var/run/mysqld/mysqld.sock
  
  If neither of these values work, please create a page called info.php and place this text into it: <?php phpinfo(); ?>
  Run the page and perform a text search for SOCKET
  
  If you have the mysqli extension installed, you will find a line called MYSQLI_SOCKET, the value of that line will be the value you need to input into this field. If you do not have the mysqli extension installed, you will need to contact your web hosting provider for further assistance.
  
  Host Specific Settings for the SOCKET Value
  
  MAMP - Here is an example of a MAMP install that had configured the MySQL socket incorrectly, and the fix.
  
  One of RackForms's users has created this useful checklist for MAMP stacks, you may find it useful:
  

  For Mac users using MAMP:
  1. Drag the RackForms_pro folder into the htdocumentation folder inside the MAMP installation
  2. From the MAMP window, click Preferences... > Ports > Set to default Apache and MySQL ports > OK
  3. Create database for RackForms, making sure Collation is set to utf8_general_ci as it defaults to sweden. Default user has privileges set to all so that shouldn't be an issue.
  3. On the Form Boss Installation page:
  Database Name: whatever you just created
  Database User name: root
  Database Password: root
  DB Host: localhost
  Database Port: leave blank if you did step 2 above
  MySQL Socket Path: /Applications/MAMP/tmp/mysql/mysql.sock
  
  BlueHost - Your socket value will probably be: /tmp/mysql.sock

  HostGator/GoDaddy/HostMonster - Your socket value is generally: /var/run/mysqld/mysqld.sock
  
  Back to Install Screen Image

•  D-3  Database DSN - (NOT REQUIRED) - This field allows us to define a database DSN for use with ODBC connections. This field is only used for created forms, not the RackForms editor, and is thus not required.
  
  Back to Install Screen Image
•  E  DB Host - Please pay close attention to this one, the value used will depend on the database type:
  
  MySQL - In 95% of the installs you do this should be localhost. If you choose MySQLi as your Database Vendor then you can generally ignore this field. However, if you choose PDO you will probably have to set the MySQL Socket Path setting as well.
  
  The good news is RackForms will attempt to set the MySQL Socket Path value for you by inspecting your servers configuration, runtime values, and ini output. In most cases, you can simply leave the value as set.
  
  Here are a few common values for Database host:
  
  GoDaddy Shared Hosting - The host name will generally be a long string such as: host.db.4757614.hostedresource.com
  
  HostMonster/HostGator - Your host name should be: localhost, MySQL Socket Path: /var/run/mysqld/mysqld.sock
  
  BlueHost - Hostname: localhost, socket value will probably be: /tmp/mysql.sock
  
  
  MSSQL - SQL Server Express will generally be MACHINENAME\SQLEXPRESS or MACHINENAME\SQLSERVER. On production systems or web farms that use SQL Server Professional, you generally use the ip address of the database server or its domain name.
  
  Back to Install Screen Image

• General Notes on Database Information - Both MySQL and MSSQL need to have the database schema and user defined before installation. In other words, you will not be creating schema and users with the RackForms installer, just using the login credentials from items   B ,  C  and  D  to create new tables and add optional stored procedures to an existing schema.
  
  This means that while you can create and use an exclusive 'RackForms' schema, you do not need too. You can safely install RackForms into an existing schema without fear of deleting existing objects so long as your existing objects do not begin with fb_. To that end, all RackForms database tables and optional stored procedures are prefixed with fb_
• 
  MySQL SSL - RackForms supports MySQL encryption for in-flight data. To use this feature we'll need to configure our database server to accept encrypted connections, as well as define the locations of our various certificate files. Learn more about this process here.
• 
  When properly set up on the database side, their are three files we need to define locations for in order to use MySQL encryption:
  
  - MySQL Client Key File
  - MySQL Client Certificate
  - CA Cert
  
  These files are input on the installer screen after checking the Use MySQL SSL check box.
  
  Back to Install Screen Image

User Information

•  F  Password Salt - RackForms uses password + salt encryption, this field simply needs to be a string of random characters that are used as the randomizing salt. It is recommenced that you use at least 20 characters for this field.
  
  Back to Install Screen Image

•  G  User Name - This is the login name you will provide to RackForms to log in to the manager.
  
  Back to Install Screen Image

•  H  User Password - The plain text password used to log in to RackForms.
  
  Back to Install Screen Image

•  I  User Email - Your primary account email address. Used for lost passwords.
  
  Back to Install Screen Image

•  J  Server TimeZone - Select your time zone from the list. Many PHP installations do not have a time zone set in the .ini file, this setting will ensure your form submission times match your preferred server time zone. If you do have this value set however, it will auto-populate.
  
  Back to Install Screen Image

•  K  My Doamin Key - This is the domain name value RackForms will check against when you run the application.
  
  The best way to ensure your do this step correctly is to access the RackForms installer the same way you always will. For example, if you access your RackForms installation via: www.rackforms.comsample.com, you'll always want to use www.rackforms.com If you were to use, for example sample.com as the license create value, then you will always need to access RackForms without the www.rackforms.com
  
  The same rule applies to sub-domains.
  
  Also important is to note that any value that includes http:// will not be accepted by the installer, as such a value is never right insofar as how RackForms validates domains. If such a value is entered the installer will prompt you and remove the value.
  
  Instructions on how to obtain a license key are included in your original sales receipt.
  
  Back to Install Screen Image

• General Notes On RackForms User Information - Password salt, as mentioned above, should be at least 20 characters but can be any number you like. The more characters the better, however.
  
  You will be able to update your User Password and email at any time after installation.
  
  Your PHP .ini file may already have a date.timezone = configuration property set. Setting one here will override that setting when running RackForms scripts only.
  
  Back to Install Screen Image

When all fields are filled out to your satisfaction click the Install button.  M  

An important note on how the installer treats existing tables and data:
If you install RackForms into an existing schema, no data is lost or overwritten except for any matching admin account that has the same name as an existing one. For example, if you first install RackForms with the admin 'User Account' name of 'admin', then re-run the installer with 'admin' as the 'User Account' name, the existing admin account is removed and the new one is used instead.

If the process completes without any errors you will receive a success message. You are then instructed to remove or rename the install file. Perform this action and you're finished with the installer. You may proceed to Final Steps.

Resolving Errors

If you receive an error message, follow the on-screen instructions to resolve the issue. The most common errors will be:

Error: softException in Application.cpp:668: Directory
This class of error means we have a permission error for our output folder, as the full error text describes:

SoftException in Application.cpp:668: Directory "/home/user/public_html/forms/output" is writeable by group, referer: http://example.net/forms/app/editor.php

To fix this error we'll need to set the permissions of the output directory to 755 or lower:

Please note we'll see this error text in the error log of our server, which means we'll need access to the error logs in the first place. Many hosting providers give access to this file via a Logs > Error Log icon.

ERROR: Could not write config file.
This will happen if you have not set the proper permissions on app/config.php and app/movefiles/config.php
To remedy this, make sure those files are writeable by the account the web server is running as. In Unix/Apache environments, setting -644 or -664 on both config files and -755 on /output and all directories inside /output will suffice (more on file permissions).

In Windows/IIS environments, you'll want to make sure the IUSR or IUSR_MACHINENAME accounts have read/write permissions on the /output directory and config.php files. In many cases, you will need to add the IUSR or IUSR_MACHINENAME accounts via the security tab the file or folders properties. Alternatively, you can install your PHP binaries into the /inetpub folder to inherit IIS permissions.

If you use Windows with Apache, you'll want to set your permissions using the account Apache runs as.

ERROR: Database not created properly, or an account already exists.
This error will trigger if their was a problem with the SQL installation script portion of the installer. You may want to clear out any database objects from a previous installation, or try installing to a new schema name.

ERROR: Database driver not installed.
You will see this error if the appropriate PDO database driver is not installed, or if PDO extension itself is not installed. On Windows you'll need to edit you PHP .ini file to include the PDO Extension as in: extension=php_pdo.dll, and also to include the proper driver as in: extension=php_pdo_mysql.dll

ERROR: Could not connect to the Database. Check your Username, Password, and Host settings.
You will see this message if your connection information is not correct. As the message states, this would be due to schema/username/password problems, or the host name not being correct.

MySQL Specific
If running MySQL, your local host name will be localhost, or if being served through a hosting company, possibly an ip or domain name such as 'sql101.secureserver21.net'.

You may also want to check out any problems with the MySQL socket, explained here.

SQL Server Specific
If running Microsoft SQL Server remember that you may need to specify host name + instance. For example, COMPUTERNAME\SQLEXPRESS--though not always. Sometimes your DBA will set up the server to just have a server name.

One final point on SQL Server, RackForms uses SQL Server Authentication Mode, not Windows Authentication. This means in your server properties you will need to select SQL Server and Windows Authentication mode from the 'Server authentication' radio boxes.

ERROR: I could not create the MySQL stored procedures! (MySQL only when attempting to use Stored Procedures)
This error will be triggered if your MySQL database did not allow the RackForms installer to create necessary stored procedures. This could be because your web hosting provider, despite supporting MySQL 5, has unnecessarily removed the proper privileges your database user needs to create and use stored procedures: CREATE ROUTINE ALTER ROUTINE and EXECUTE (this may be the case if you are on a 'shared hosting' plan).

If this error can not be resolved (you can't GRANT the proper permissions), you can simply uncheck the Use Stored Procedures Box. RackForms will run the same as if you installed the procedures.

Fatal error: Cannot clone object of class PDO due to 'zend.ze1_compatibility_mode'
This means you have a legacy php.ini directive set which is not needed, and can safely be disabled. Please see here for a description of the directive. The fix this error, you simple need to set the zend.ze1_compatibility_mode  directive to be 0.

Resolving Login Errors

Their have been a few instances of users being able to install the software without error but then not be able to login. The most common cause of this is your hosting provider not configuring MySQL correctly.

Sometimes this can come in the form of permission errors. In order for RackForms to run correctly when using stored procedures, for example, your database user needs CREATE ROUTINE, ALTER ROUTINE and EXECUTE permissions.

The easiest way to check for execution privileges is to open the app/config.php file in you RackForms directory. Look for:
define('DEBUG', '0'); and change it to: define('DEBUG', '1');

This will enable debug mode, which will display any errors encountered after a login attempt. If you receive an error, copy it from your web browser display and send it to support to support@rackforms.com

ERROR: 500 Server Error When Trying to Login.
This rare error can occur on servers with a broken MySQLi extension. The simple solution is to select PDO from the Database Vendor list and reinstall, though you'll want to contact your hosting provider and have them address this condition immediately.

Resolving Editor Errors

It has come to our attention that iSkysoft iMedia Converter may interfere with the WYSIWYG text editors in RackForms. If this happens you'll usually see the WYSIWYG editor box chopped in half when expanded. To fix this issue you'll need to disable this program.

Final Steps

You've run the installer and all is well. To finish up, you'll need to ensure RackForms has a few extra tools to perform its job.

Please follow the steps below to complete the RackForms install process.

File Uploads

IIS users planning to allow file uploads greater than 4MB on IIS 6 and 28 MB on IIS 7 will want to see this link for a detailed description or how to allow for larger values. Failing to do this will cause CONTENT_LENGTH_TOO_LARGE errors.

CAPTCHA SYSTEMS

Default CAPTCHA

GD Library + FreeType
If you plan to use the CAPTCHA security option with your forms, you must have the GD and FreeType libraries installed and enabled. On Windows make sure your PHP .ini has the extension enabled: extension=php_gd2.dll, or on *nix platforms, that PHP has been compiled with GD and FreeType support. More Info on GD.

Font Files
Along with the GD library, RackForms requires you have the monotype.ttf font available for use during form export if you choose to use the Default CAPTCHA feature.

On Unix machines this is a non-issue. RackForms comes with the necessary font and exports it with every form.

On Windows machines, there is a know bug that prevents Windows from releasing the font file after use. The end result is the job folder cannot be removed properly using the RackForms job editor.

The solution is to grab the monotype.ttf font file from:

\rackforms\app\movefiles\security\Captcha

And install the font file as you would any other font. RackForms will then use the default /Windows/fonts font directory whenever the font is needed instead of the one located in the job folder.

If you do not have access to the fonts folder, or your hosting provider will not allow you to install or refuses to install the monofont.ttf font file for you, you may need to look up your server version and cross reference that with a list of know Windows fonts. Find a suitable True Type Font (.ttf) file, and open up:

\rackforms\app\movefiles\security\Captcha\CaptchaSecurityImages.php

Replace the text monofont.ttf with the name of the new font file. Create a test job and export. You may need to experiment to find a good combination. A good choice would be: Lucida Sans Unicode and Lucida Console on older servers, and Cambria

reCAPTCHA
As of build 557 RackForms supports the reCAPTCHA system. In order to use this CAPTCHA method you will need to have an account at recaptcha.net. Creating an account is very simple, but you want to be mindful of what type of account you create.

If you plan on creating forms and using reCAPTCHA for more than one domain, you'll want to check the Enable this key on all domains (global key) checkbox. Selecting this feature means you can create a shortcut in RackForms, in that no matter what site you create a CAPTCHA block for, you can edit the /app/movefiles/security/secure_submit.php file to include the two keys you receive from the reCAPTCHA sign up process, and those key's will work for all domains.

This is a short cut because if you do not provide the /app/movefiles/security/secure_submit.php file with your reCAPTCHA key's, you will need to input them for every form you create that uses reCAPTCHA. For many uses this will be a huge time draw.

Finally, it should be noted that while you do not need a global key to take advantage of the /app/movefiles/security/secure_submit.php hard code trick, it may come back to bite you if you hard code single domain account key's and then try to use that key set on an invalid domain. It's always best to plan ahead!

3D Captcha
Similar to the Custom Captcha Method, this Captcha type needs a custom font installed to work. You will find the font file at:

\rackforms\app\movefiles\security\3DCaptcha\src

You will need to install the font on Windows systems, on Unix like systems you do not need to do anything else.

Cannot Generate Forms Issue
Their is a class of error by where RackForms will install just fine but we cannot create forms. Common symptoms of this will be correct folder permissions for the output directory, but saved form folders do not contain any generated page code.

A good trouble-shooting technique for such problems is to start by checking for any files called error_log in your File Manager within the RackForms directory structure, particularly the app/lib folder. If such a file exists this means the web hosting company has disabled normal error logging and instead is creating custom log files in the same folder as the offending code.

A common error entry in these cases will be one or more instances of:

[10-Oct-2011 11:49:56] PHP Fatal error: Uncaught exception 'Exception' with message 'String could not be parsed as XML' in /home/matt/public_html/RackForms/app/classes/XMLParser.php(1) : eval()'d code(1) : eval()'d code(1) : eval()'d code:29
Stack trace:
#0 /home/matt/public_html/RackForms/app/classes/XMLParser.php(1) : eval()'d code(1) : eval()'d code(1) : eval()'d code(29): SimpleXMLElement->__construct('')
#1 /home/matt/public_html/RackForms/app/classes/Main.php(1) : eval()'d code(1) : eval()'d code(1) : eval()'d code(159): XMLParser->parse_php_form(NULL)
#2 /home/matt/public_html/RackForms/app/lib/generate_form.php(1) : eval()'d code(1) : eval()'d code(1) : eval()'d code(10): Main->generate_php_form()
#3 /home/matt/public_html/RackForms/app/lib/generate_form.php(1) : eval()'d code(1) : eval()'d code(1): eval()
#4 /home/matt/public_html/RackForms/app/lib/generate_form.php(1) : eval()'d code(1): eval()
#5 /home/matt/public_html/RackForms/app/lib/generate_form.php(1): eval()
#6 {main}

It's unfortunately impossible to say what the exact fix is, but it's a good bet it's mod_security related. To learn more follow this link to a section earlier in this document.

Licensing Firewall

RackForms is licensed software, which means it requires internet access from your server to our licensing machine. This process is usually transparent, though occasionally some Firewalls will block access to our server's IP address. If you find your login does not work or creates messages about invalid license, please make sure the following IP address is not being blocked: 45.33.2.105

A Note On Server Security
One of the most effective things you can do to secure your server is to reduce the so called 'surface area' of your machine. This simply means we disable as many ports of entry as possible when not in use. Of course on many hosting platforms this will not be an option, but if you can, disable FTP, SSH, and any other service when not in use.

In other words, although it may be a pain to always have to turn it back on, your FTP server should NEVER be running when your not specifically placing new files on the site. Turn it on, add files, and turn it off immediately.

As an alternative, we can setup a firewall (though usually this is only available on dedicated servers), that blocks all users not matching your exact IP address for each service. For example, we would create a rule in IP Tables that says only the IP address: 76.455.322.22 is allowed access to the FTP server. This way we can leave services turned on, and only we can access them. Again though, this is only valid for users that have access to to a firewall. In most shared hosting plans this is not the case.

We can also, if possible, modify critical components with the same logic. For example, phpMyAdmin runs on port 443, which means it's impossible to create a valid firewall rule to block IP's. We could however, add custom PHP code to phpMyAdmins login page, or add an Apache rewrite rule that checks for and blocks all non-valid IP addresses.

By the same token, disable ports that are not used, even for services you think you may need. For example, many dedicated servers will run email deamons for SSL traffic (pops, etc). If you do not use email traffic encryption, then we do not need those ports running.

A good source of information on this topic is for the excellent nmap tool. In short, the best path to security starts with understanding your own networks limitations and weaknesses.

Ready to go!
And that's it. RackForms is now fully installed and ready to go. Should you encounter any problems not covered in this document, please visit us on the forums, or drop us a line.