UserBase: Installation Instructions

Instructions: Apache on Mac/Linux/BSD
Instructions: Apache on Windows
Instructions: IIS on Windows
FAQ
Password-Protect Your Webpages and Directories
Support
Updates
ChangeLog

Quick Instructions for Most Servers (Apache on Linux, Mac OS X, BSD)

Most servers already have MySQL installed, but if yours doesn't, then download and install the free MySQL Community Server, and then create a database and a MySQL user account.

Unzip your userbase.zip file, then upload the contents of the www.example.com folder onto your website. Then visit the following address, replacing example.com with your own domain name:

www.example.com/cgi-bin/userbase.cgi

If you see a message about adjusting your database prefs, then UserBase is working properly. You should now read the FAQ.

If nothing works, read the full instructions.

Quick Instructions for Apache-on-Windows Servers

Other than Apache itself, the only things strictly required are Perl and MySQL. If your server doesn't already have Perl installed, download and install the free ActivePerl. You may need to reboot after installing it. Open a command prompt and type perl -v and if you get some output about Perl and its version info, you should be all set.

If you had to install Perl, you will also need to install the DBD::MySQL Perl module, and possibly the MIME::Lite, MIME::Base64, and Authen::SASL modules (if you want to use any of the email features), by opening the Run dialog or a command prompt and then typing ppm install DBD-mysql (or ppm install MIME-Lite etc). Or you can run just the ppm command by itself to use the graphical installer.

Most servers already have MySQL installed, but if yours doesn't, then download and install the free MySQL Community Server, and then create a database and a MySQL user account.

Now unzip your userbase.zip file, then upload the contents of the www.example.com folder onto your website. Then visit the following address, replacing example.com with your own domain name:

www.example.com/cgi-bin/userbase.cgi

If you see a message about adjusting your database prefs, then UserBase is working properly. You should now read the FAQ.

If nothing works, read the full instructions.

Quick Instructions for IIS-on-Windows Servers

If your server doesn't already have Perl installed, download and install the free ActivePerl. You may need to reboot after installing it. Open a command prompt and type perl -v and if you get some output about Perl and its version info, you should be all set.

If your server doesn't already have MySQL installed, download and install the free MySQL Community Server. Once it's installed, create a database and a MySQL user account.

Unzip your userbase.zip file, then open the www.example.com folder and move the contents of the cgi-bin folder into the login folder. Then delete the cgi-bin folder. Upload the "login" folder onto your website, then visit the following address, replacing example.com with your own domain name:

www.example.com/login/userbase.cgi

If you see a message about adjusting your database prefs, then UserBase is working properly. You should now read the FAQ.

If nothing works, read the full instructions.

Full Instructions for Most Servers (Apache on Linux, Mac OS X, BSD)

Want us to install it for you? Just purchase the UserBase Installation Package. We also provide customization and integration services -- just ask!

Note I: Do not edit the userbase.cgi file unless absolutely necessary; instead, edit userbase_prefs.cgi for all your customizations.

Note II: if you are using Windows on your desktop, and when you open the *.cgi file, the lines all appear to be crunched together, try opening it in Wordpad (not Word) instead. In Wordpad, save the file; this should fix the line-endings so the file's contents appear correctly in other editors like Notepad.

On your website:

First, complete the quick instructions.
Set the permissions on /cgi-bin/userbase.cgi (aka, chmod it) to world-readable and world-executable, that is, a+rx or mode 0755. Do NOT use 0777.
Set the permissions on the /cgi-bin/encdata/ directory to world-readable, -writable, and -executable, that is, a+rwx or mode 0777.
In your browser, go to yoursite.com/cgi-bin/userbase.cgi and follow the brief instructions that it gives you. (It will instruct you to set the database options in userbase_prefs.cgi. Once these are set properly, UserBase will create a README file in your encdata directory containing your initial login username and password.)
If you get an Internal Server Error, it's most likely a permissions problem. See this page for more details.
(Optional) For maximum security, consider purchasing and installing an SSL certificate on your server. This allows you to use https:// URLs instead of http:// URLs, which encrypts all communications between your website and its visitors.
Read the FAQ.

UserBase is now ready to use, and you can access it by visiting yoursite.com/cgi-bin/userbase.cgi (or yoursite.com/login/ if your server supports it).

Full Instructions for Apache-on-Windows Servers

Want us to install it for you? Just purchase the UserBase Installation Package. We also provide customization and integration services -- just ask!

Note I: Do not edit the userbase.cgi file unless absolutely necessary; instead, edit userbase_prefs.cgi for all your customizations.

On your website:

First, complete the quick instructions.
In your browser, go to yoursite.com/cgi-bin/userbase.cgi and follow the brief instructions that it gives you. (It will instruct you to set the database options in userbase_prefs.cgi. Once these are set properly, UserBase will create a README file in your encdata directory containing your initial login username and password.)
If it doesn't execute or you get errors, you may need to change the first line of the userbase.cgi file from #!/usr/bin/perl to either #!perl or #!c:\path\to\perl.exe
If it doesn't execute or you get errors, you may need to rename the script and its prefs file from a .cgi extension to a .pl extension.
If you get errors about UserBase being unable to delete something from the encdata folder, you may need to set a "Delete" bit on the folder's properties.
(Optional) For maximum security, consider purchasing and installing an SSL certificate on your server. This allows you to use https:// URLs instead of http:// URLs, which encrypts all communications between your website and its visitors.
Read the FAQ.

UserBase is now ready to use, and you can access it by visiting yoursite.com/cgi-bin/userbase.cgi (or yoursite.com/login/ if your server supports it).

Full Instructions for IIS-on-Windows Servers

Want us to install it for you? Just purchase the UserBase Installation Package. We also provide customization and integration services -- just ask!

Note I: Do not edit the userbase.cgi file unless absolutely necessary; instead, edit userbase_prefs.cgi for all your customizations.

On your website:

First, complete the quick instructions.
In your browser, go to yoursite.com/login/userbase.cgi and follow the brief instructions that it gives you. (It will instruct you to set the database options in userbase_prefs.cgi. Once these are set properly, UserBase will create a README file in your encdata directory containing your initial login username and password.)
If it doesn't execute or you get errors, you may need to complete one or more of the following steps (most are not necessary on most IIS servers, so try one at a time):

Rename the script and its prefs file from a .cgi extension to a .pl extension.

Change the first line of the userbase.cgi file from #!/usr/bin/perl to either #!perl or #!c:\path\to\perl.exe

For the /login/encdata folder, do the following: right-click on the folder, choose Properties, and go to the Security tab. Find or add the IUSR_computername account, and give it "Full Control". This account is sometimes called the Internet Guest Account.

Run the inetmgr command and change the CGI web service extension from "prohibited" to "allowed". If your Web Service Extensions list doesn't include an item for Perl CGI scripts, then add a new one (named something like "Perl CGI", or "CGI Scripts", etc -- the name is not important), and for its "Required Files", enter C:\Perl\bin\perl.exe "%s" %s (adjust the path as necessary for your Perl installation)

Run the inetmgr command and right-click on the website and choose Properties. Go to the "Home Directory" tab, then to "Application Settings", and set "Execute permissions" to "Scripts and Executables".

Run the inetmgr command and go to "Application Settings" then "Configuration", and add an application extension for .cgi (and .pl) with the executable set to: C:\Perl\bin\perl.exe "%s" %s (adjust the path as necessary for your Perl installation)

Run the inetmgr command and right-click Default Web Site (or your site's name, if different). Then click New -> Virtual Directory and follow the prompts, entering "login" as the name of the virtual directory, and choosing UserBase's login folder (c:\inetpub\wwwroot\login\ by default) for the path. For Access Permissions, check (enable) the Read, Run Scripts, and Execute boxes. When finished, right-click the new virtual directory and choose Properties -> Application Configuration -> Mappings, and make sure there's a .cgi (and/or .pl) extension there, mapped to the C:\Perl\bin\perl.exe "%s" %s command (or your server's path to perl.exe).

If you get errors about UserBase being unable to delete something from the encdata folder, you may need to set a "Delete" bit on the folder's properties.
(Optional) For maximum security, consider purchasing and installing an SSL certificate on your server. This allows you to use https:// URLs instead of http:// URLs, which encrypts all communications between your website and its visitors.
Read the FAQ.

UserBase is now ready to use, and you can access it by visiting yoursite.com/login/userbase.cgi (or yoursite.com/login/ if your server supports it).

Password-Protection Options

Password-Protect Individual Webpages: PageLock
Password-Protect Whole Directories: DirLock
Password-Protect Files and Folders: FileChucker
Password-Protect Individual Pages Without PHP: BasicLock
Password-Protect CGI Scripts: CGILock

PageLock: Password-Protect Individual Webpages

(requires: PHP exec function)

In newer versions of UserBase, simply login with your admin account, then go to the Admin menu and click PageLock. Or, if you're using an older version, follow these instructions instead:

If your server supports PHP (most servers do) then you can use UserBase's PageLock feature to password-protect web pages on it. First, if the web page that you want to protect has some extension other than .php, such as .html, then either a) change its extension to .php, or b) configure your server to parse .html files as PHP files. Then, insert the following code as the very first line in your protected web page (it's split onto multiple lines here for readability; either single or multiple lines is fine):

<?PHP

$groups_allowed = "member,other_groupname";

$users_allowed = "Joe,Steve,Bill";

require($_SERVER['DOCUMENT_ROOT'] . "/login/ublock.php");

?>

Within that code, you should adjust the $groups_allowed and $users_allowed lists to control access the way you want to for that particular page. You can delete the $groups_allowed line if you only want to use $users_allowed, and vice-versa, but you must have at least one of them. To add your own groups, log in to UserBase with your admin account, go to the Main Menu / Account Center page, and click the Manage Groups link; on that page you'll find an Add New Group link. After you've added your new group, you can go to the Manage Users page and edit individual accounts to add them to whichever groups you want to.

Now when you visit that page in your browser, if you're not logged in, it will require you to log in first.

DirLock: Password-Protect Whole Directories

(requires: .htaccess RewriteEngine and RewriteRule commands)

In newer versions of UserBase, simply login with your admin account, then go to the Admin menu and click DirLock. Or, if you're using an older version, follow these instructions instead:

To password-protect a whole directory, without using PHP, and without editing individual files within the directory (which means all the pages and files will have the same permissions), use the DirLock feature via the /login/protected/ folder from the UserBase installation. This method protects all file types.

Either copy the whole "protected" folder to the top level of your website, or, if you already have a directory there that you want to protect, then just copy the .htaccess file from the /login/protected/ folder into your existing directory. Adjust the $PREF{protected_directory_01} settings in your userbase_prefs.cgi file, and also adjust the .htaccess file to match those settings if necessary (not usually required unless you've got more than one protected directory). Now any URL on your site starting with www.yoursite.com/protected/ will run through UserBase and will be protected according to your settings.

If your server gives an error because of the .htaccess file, then it probably means your server is configured to not allow .htaccess files, or at least, not the specific commands in this .htaccess file; in this case, you'll need to either ask your hosting company to allow them, or else use one of the other password-protection options.

FileChucker: Password-Protect Files and Folders

(requires: FileChucker)

Use FileChucker together with UserBase for advanced protection of files and folders. FileChucker is an online file manager with an upload progress bar and full-featured browse/download page, where you can set individual features to members-only (such as uploading, browsing, downloading, etc), or enable private per-user subfolders, or set totally custom per-folder permissions, all based on your UserBase users and/or groups.

BasicLock: Password-Protect Individual Pages Without PHP

(requires: nothing special. for servers with limited capabilities)

If your server doesn't have PHP, or if your hosting company won't allow you to use the exec() or include() PHP functions, and you don't want to switch to a better hosting company, you can still password-protect your webpages with the BasicLock feature. To do so, you must create a directory to store your protected pages in, and you must add 2 lines to the top of the HTML code on each page that you want to protect. Then you need to take steps to protect the directory containing your pages, and finally you must choose how you'll link to the protected pages. The following paragraphs will explain these steps in detail.

Note that while these initial setup instructions are a bit long, they're relatively simple to do; and once the initial setup is finished, then creating a new password-protected page is simple: just do step #3 for the new page.

The first step is to create the directory which will hold your protected webpages. We won't be serving the webpages directly from this directory, so its name will never be displayed in any of your links or page addresses. And in fact, you'll want to give the directory a slightly long name and then keep its name a secret -- this is a bit of security through obscurity, but it's not the only security we'll be using. For example, you might name this directory "protected-webpage-storage-directory".

Now you must decide where to place this directory. If your server allows you to create directories outside of your website's document-root -- that is, directories that cannot be accessed on your website -- then do that for this protected directory.

If you can't store directories on your server outside of your website's directory, that's OK; we have other ways to protect the folder. Just put it in the top level of your website in this case. Most servers give you a way to specify that a given directory cannot be accessed at all through the web; on Apache servers this is accomplished by creating a file called .htaccess within the directory and then putting the following lines into it:

RewriteEngine On
RewriteRule .* - [F,L]

With that file in place in your "protected-webpage-storage-directory" folder, try visiting www.yoursite.com/protected-webpage-storage-directory/ and you should get a "Forbidden" message. If so, then it's working properly. If you get an error, then your server may not allow those commands in an .htaccess file. So delete the .htaccess file and try this one last trick:

On most servers, any file with a .cgi extension will be treated as a script and executed, instead of being simply displayed as a text file or webpage normally would. We can use this to prevent our protected pages from being served. Just name your files with a .cgi extension instead of the normal .html extension. (And don't worry: in the addresses and links to your pages, this extension won't show up -- you can still use .html as usual.) Create a test page named test.cgi and put a few lines of text into it, then upload it to your server into your "protected-webpage-storage-directory" folder. Then try to access www.yoursite.com/protected-webpage-storage-directory/test.cgi. You should get an "internal server error" or similar message saying that the file couldn't be displayed or executed. If you don't, and the file is instead displayed as a normal webpage, then you're out of luck. You'll just have to rely on the fact that the name of your protected folder is a secret -- or switch to a better hosting company already!
The second step is to tell UserBase where you've put the protected directory, by editing your userbase_prefs.cgi file and adjusting the $PREF{protected_pages_directory} setting. If the directory is within your document root, then you should start this setting's value with %PREF{DOCROOT}, for example "%PREF{DOCROOT}/protected-webpage-storage-directory". If your protected directory is one level above your docroot, then you could set this to "%PREF{DOCROOT}/../protected-webpage-storage-directory". Or if you know the full literal path to the directory, you can of course set it to that.
The third step is to put one or both of the following 2 lines at the very top of the HTML code for each web page that you want to protect:




Of course, adjust the usernames and groupnames for the accounts and groups on your own site. Then upload the page into your "protected-webpage-storage-directory" folder. Now because of the protections we applied in step #1 above, you should NOT be able to access this page through your website by going to www.yoursite.com/protected-webpage-storage-directory/pagename.html -- unless of course your server didn't support any of the protections that we tried to apply.
The fourth and final step is to decide how you want to access your protected pages. The simplest way is to simply use the full URL to UserBase, like this: www.yoursite.com/cgi-bin/userbase.cgi?ppge=pagename.html
However, on most servers, we can use a much nicer shorter URL.

Hopefully your server is a normal, decent server that supports URL rewriting. In this case, you can create a directory -- call it "private" or whatever you want to -- and then put a .htaccess file into it containing the following lines:

RewriteEngine On
RewriteRule (.*) /cgi-bin/userbase.cgi?ppge=$1 [L]

Now visit www.yoursite.com/private/pagename.html and UserBase will automatically transparently load the file pagename.html from your protected directory, not from this "private" directory, and -- if you have permission to view it -- it'll display the page.

If that doesn't work on your server, you can try using an .shtml file instead: inside your new "private" directory, create a file called index.shtml, and put the following line into it:


Now visit www.yoursite.com/private/?pagename.html (note the question-mark). If that also does not work, then you can try moving your userbase.cgi and userbase_prefs.cgi files from your cgi-bin directory to the top level directory of your website -- i.e. www.yoursite.com/userbase.cgi -- because many servers allow CGI execution from any directory, not just within the cgi-bin directory. And you can even rename userbase.cgi to whatever you want, as long as it has a .cgi extension, and as long as you rename the prefs file to match. Once you've moved it, visit www.yoursite.com/userbase.cgi?ppge=pagename.html. If that also doesn't work, then it's time to find a better hosting company, seriously. In the meantime, you'll have to put UserBase back into your cgi-bin folder and just use the full URL to it: www.yoursite.com/cgi-bin/userbase.cgi?ppge=pagename.html

With this method, the filenames that you use in your addresses and links can have whatever extension you'd like. It's generally best to stick with .html but if you have reasons for using a different extension that's no problem.

CGILock: Password-Protect CGI Scripts

(requires: nothing special)

You can also use UserBase to password-protect other CGI scripts. For Encodable apps, just enable the $PREF{integrate_with_userbase} setting. For other CGI scripts/apps, use the CGILock feature via the code in the example script userbase_caller.txt. Just copy and paste the code from it into your existing CGI script.

Support

For many issues, the best place to get support is in the FAQ.

If you are getting an Internal Server Error message when you try to access UserBase on your server, please try the solutions on our Internal Server Error page.

If you're getting errors about missing Perl modules, please see our instructions on how to install Perl modules.

If you still need help, you can contact us.

UserBase

Website Login System and User Manager