GreatWebScripts.com Well Designed Scripts for the Busy WebMaster

GreatWebBook Users Guide



Install Guide GreatWebBook

 

Table of Contents

 

Introduction........................................................................................... 1

Requirements......................................................................................... 1

Installation............................................................................................ 2

Upgrade.................................................................................................. 3

Setup Options......................................................................................... 4

Security Options.................................................................................. 8

Your First Test Drive............................................................................ 9

Creating a Theme................................................................................ 14

Customizations.................................................................................... 14

Tips....................................................................................................... 15

 

 

Introduction

 

Thank you for trying the GreatWebBook® WebSite Guestbook.  In addition to fighting off SPAMMERs, the webbook is a pleasant addition for your visitors.  And it’s a great way to solicit comments and suggestions about your site.

 

Installation of GreatWebBook® is designed to be a 15-minute operation.  The setup screen allows you to customize your installation to your own tastes.  There is actually very little information that the script needs to run as most of the parameters are set to default values so you can get up and running very quickly.

 

There’s also a quick view section entitled Your First Test Drive, which will walk you through the various features.  We recommend this to all first-time users.

 

 

Requirements

 

Installation of GreatWebBook® requires the following:

  1. A webserver or web hosting account running (almost) any major Operating System (Linux, Windows, Unix)
  2. PHP (4.3.1 or higher recommended for security, but above 4.0.3 will suffice).

 

If your hosting account does not meet the requirements above, GreatWebBook cannot be installed on your account. 

                    

You will also need access on your local machine to an archival utility such as WinZIP or WinRAR to extract the product files, and an FTP Client such as FileZilla or FTP Commander to place the files on your webhosting directories.

 

 

Installation

 

This section details how to install GreatWebBook® if you have never installed a copy on your site before.  See here for upgrade instructions if GreatWebBook is already installed and you are trying to upgrade to a later version.

 

  1. Unzip the GreatWebBook delivery package to your local drive.
  2. FTP all files to your host.  We’ll assume you use a subdirectory /guestbook.
    1. All .php, .css, .txt and .js files should be uploaded in ASCII mode, while all graphics should be uploaded in BINARY mode. If you are unfamiliar with what this means please refer to your FTP client documentation. In most cases this is all handled transparently by your FTP Client but if you have problems later you should be sure the files were uploaded correctly as described here.
  3. Run the installer by pointing your web browser to

http://www.yourhost.com/guestbook/gwadmin.php.

(If you changed the subdirectory from Step 2 above, use that subdirectory name)

 

You should see the GreatWebBook Setup Script Display (Figure 1: Script Initial Display) below appear.  It prompts you for the initial Admin Login / Password.

 

 

 

Figure 1: Script Initial Display

 

Enter the Login Name / Password you want to use as the guestbook administrator and select Login. (Note: you can change your username and/or password later, but you must know the old one to change it!! (Write it Down!!)  You will be presented with the Setup Display as below.

 

 

Upgrade

 

This section details how to upgrade to a later version of GreatWebBook from an earlier one.  It assumes GreatWebBook is already installed and working at your site.  See here for information on how to install GreatWebBook if you do not have an earlier version installed.

 

Before starting, backup your data, including the php files, and especially the data files.  Reference your web hosting provider documentation for steps on how to backup your database.

 

  1. Backup your data!
  2. Unzip the archive to your hard drive
  3. FTP the files up to the GreatWebBook directory on your web host.

 

 

Setup Options

 

The Setup Options Display (Figure 2: Setup Initial Display) allows you to select various parameters that affect how GreatWebBook® works.   The Setup Options can be run anytime you want to update your selections.  When you first enter Setup, you are presented with the Activity Log display, which lists the actions of GreatWebBook.

 

 

Figure 2: Setup Initial Display

 

The Setup options are split into four tabs:  Notice the color coding of the various settings:

The parameters are color coded to prompt you in making updates: green tabs can be freely changed; yellow tabs affect the security or workings of the program and you should consider carefully before changing; and red tabs should not be adjusted without GreatWebScripts support.

 

  1. General: customize overall system parameters.  It is recommended you review and set these according to your site needs.
  2. Security:  Set parameters defining the security and SPAM fighting aspects of the guestbook
  3. Activity:  This is the tab you open to be default, and is displayed in the Figure above.  It contains the Activity Log for GreatWebBook, listing the dates and IP addresses corresponding to entries added, deleted, or modified, and entries rejected as SPAM along with an explanation of why it was rejected.  You should review this log periodically to understand what activities GreatWebBook is taking.
  4. HackerTrap: If you have HackerTrap installed, this tab is available.  It allows you to specify whether and under what conditions a detected SPAMMER is blocked.

 

If you change any data in any of the tabs, press the Save Button to commit the changes or the Revert button to cancel the updates.

 

Select the General tab and your display will appear similar to Figure 3: Setup Options - General Tab

Figure 3: Setup Options - General Tab

Some of the items you’ll want to customize are:

 

General Tab:

 

  1. Site Title: The name of your site, displayed at the top of each page.
  2. Site Subtitle: Use this as a caption or banner for your site if you want.
  3. Site Notice: This is designed to be a small, transient notice you can display to alert your visitors of any special conditions.
  4. Server Time Offset: Set so local time display is correct; this affects the timestamps recorded in the Activity Log.
  5. Admin Email: indicate the email address where GreatWebBook should send email notifications.
  6. Logo Image: Your site logo, displayed at the top of each page.  Upload your site logo to the indicated directory and it will appear as a selection.
  7. Theme: There are several different style templates to choose from; select one that fits the overall atmosphere of your site.
  8. Enable Smilies: Smilies are small graphics that allow webbook users to express their emotions, such as .  Setting this to ENABLED allows your users to select them to add into their guestbook entry.
  9. Smilie Symbols: If you have enabled Smilies above, this converts the standard textual smilies into graphics.  The format is: 

<smilie-symbol> = <smilie-name>

where <smilie-name> is the name of a gif file.

  1. Enable Text Hilights: Setting this to ENABLED allows your users to Bold, Italicize, and Underline text.
  2. Enable Text Colors: You may add HTML colors in this list to allow your users to specify the color of the text in their Guestbook comments.
  3. Permitted HTML Tags: Enter HTML tags you want to allow your users to specify in the Guestbook comments.  Be careful entering new tags, as this could compromise the security of your book.

 

Security Tab:

 

  1. Initial Entry State: This parameter specifies whether you want the Administrator to review each guestbook entry before it is published. If set to Visible, entries are immediately visible when added by users; if set to Hidden, entries are hidden until approved by the administrator.
  2. Enable Notifications: Set to get an email notice when a new comment is added to the GuestBook. The notice is sent to the Admin Email on the General Tab.
  3. Administrator Link: Determines whether the Administrator Options link shows up on the main Guestbook page.
  4. Allow URLs: Indicates how to handle URL (HomePage) in a Guestbook Posting: Enabled: Allow URL postings (Not Recommended, as it may lead to many SPAM postings); or Disabled: No URL postings permitted
  5. Encrypt Data: provides a secure repository for your guestbook data.  Just remember to always turn this to Disabled when backing up the data file!

Each time you set Encrypt Data Files to Enabled from the security settings, the program generates a new key.  So if you Encrypt -> Decrypt -> Encrypt, you have a different key!!!!  Don’t backup with Encrypted Data Files set to Encrypt– set to unencrypted first, then backup.

  1. Expanded Character Set Processing: This setting determines how non-ASCII characters are processed. English Language guestbooks should leave this set to "Reject".
  2. Maximum Expanded Character: The largest character to accept as standard ASCII. English Language guestbooks should leave this set to "127".
  3. Token Timeout: Length of time in seconds for the Administrator Timeout. Set to zero to disable (not recommended).
  4. Enable Akismet: This is the Anti-SPAM Comment Interface. Free service, but you must obtain an API key from the WordPress Site and enter it in the Akismet/WordPress API Key field below. (Recommended)
  5. Akismet/WordPress API Key: API Key - only required to enable the Akismet Interface.  Sign up for FREE at WordPress Site. (Recommended)
  6. Verification Field Length: Number of characters in the security check field, which a user must echo back to the system.
    Set to zero to disable (not recommended!)
  7. SPAM Words Permitted: Number of SPAM Words which must be found before declaring input as SPAM.
  8. Min/Max Input Time: Maximum and minimum length of time, in seconds, a user may spend completing the comment form. This is remarkably effective in eliminating SPAM bots, as they send the results back immediately because they do not want to waste time!
    Set to zero to disable (not recommended!)
  9. Annoy SPAMMERs: Determines what actions to take when SPAM is detected.  Disabled: SPAMMERs return back to input screen. Redirect: SPAMMERs are redirected to random site.  Munge Fields: Modifies various fields from SPAMMERs
  10. SPAMMER Redirect Sites: Possible sites to where a SPAMMER is redirected if the Annoy SPAMMERs flag above is set to Redirect
    Put each entry on a new line. Precede with a 'www' but not 'http://'.
  11. SPAM Words: If your site becomes the target of a persistent hacker, you may have to add words here to prevent his specific attack.
  12. Filter Words: Here you can enter a list of words that should be filtered out from entries.  The format for entering is word:replacement, where each occurrence of word found in the entry is replaced by replacement.  If you do not specify replacement, the word is replaced by its first letter plus dashes (so banana would be replaced by b-----).
  13. SPAM Notification: Indicate what type of message you want to display if a Guestbook entry is determined to be SPAM.: Direct: Display a short message to the user that his entry was rejected because a SPAM word was found.  Obfuscate: Display a cryptic message to the user that hopefully confuses him and makes him go away!
  14. Filter Word Action: This indicates what to do when a Filter Word is encountered: Replace it with the replacement text specified as above; Delete it with no replacement; or Reject the entire entry and make the user correct it.
  15. Leet Characters: Leet characters are used by SPAMMERs to hide their text and confuse simple word filters. You've probably seen the emails that advertise Viagra as 'V1@gr@'. This section allows you to map letters that are commonly substituted for another so the filters still find the keywords.
    Every letter you specify is substituted for every SPAM word and filter you create automatically. You don't need to try and figure out how many different ways to spell the keywords; it's done for you.
    Enter the original letter, followed by all its leet values, and then a semicolon to separate the original letters. If you attempt to edit the field and completely mess things up, press the Defaults button and the original distribution values are restored (minus your updates of course).
  16. HackerTrap™ Directory: Directory where HackerTrap is installed

 

 

Activity Tab:

The Activity Log is used to review any unusual events recorded by the Guestbook

 

Reference the HELP display for more detailed information about the remaining settings.

 

You will also notice the bar along the top of the display alongside of the HELP button.  The choices here are:

  1. Logoff: terminate your administrator session.  You should always log off after completing your updates
  2. Change Password: Used to change your Administrator Login or Password.
  3. Edit Entries: Used to modify entries in your guestbook.

 

 

Security Options

 

GreatWebBook has enhanced security features to preclude your guestbook against Cross-site Scripting (XSS) attacks and your administrator account against Cross-site Request Forgery (CSRF) attacks.  As administrator, you do not need to activate nor control either feature, but you should understand the purpose and limitations of each.

 

XSS attacks are HTML / Javascript commands that might be placed into your guestbook and effect other readers and visitors to your site.  Any site that accepts and displays unknown user input is susceptible to XSS; GreatWebBook prevents your book from accepting any type of malformed code of this type.  The options you have to control it are under the Security Tab in the Parameters Section. (Note: if you do not fully understand these parameters, GreatWebScripts recommends you leave them at their default settings):

  1. Expanded Character Set Processing:  This setting determines how the guestbook responds to characters outside the Normal ASCII range.  For English-language guestbooks there is no reason to have this set to anything other than Reject; for other languages the safest option is Translate.
  2. Maximum Expanded Character: Coupled with the Expanded Character Set Processing flag, this indicates the largest character to accept as untranslated.  127 is the largest standard ASCII character.  English-languages guestbooks do not need to accept any higher values.

 

CSRF Attacks are used against the Administrator account.  They occur when you sign in to the Guestbook as the Administrator, and then browse to another site before logging out.  Since you are still logged in to your Administrator account, that second site can run commands they you are not aware of.  GreatWebBook has implemented a One-Time-Use Administrator token that is used to authenticate you and ensure a requested command is proper before carrying it out.  The options you have to control it are under the Security Tab in the Parameters Section. (Note: if you do not fully understand these parameters, GreatWebScripts recommends you leave them at their default settings):

  1. Token Timeout: This is the time in second that the Administrator token expires.  If you have not taken action within that time, the Administrator is automatically logged out.

 

If you review the Activity Log, you may see entries of the form Admin Inactivity Timeout; this indicates the Administrator account was automatically logged out due to inactivity.  It is not a cause for alarm as long as your IP Address is that listed.

 

An entry of Invalid Token! - Attempted Operation indicates that the token did not match that of the internal database.  If this is your own IP address it is usually OK (a Refresh may cause this entry); if another IP address is found you may be the (attempted) victim of a CRSF attack that was successfully blocked.

 

The allowed password for the Administrator account has also been restricted.  The password must now contain mixed case (capital and lower case) letters, and at least one digit or special character.

 

 

 

Your First Test Drive

 

Select Edit Entries from the top command band.  You’ll be taken to a Blank Guestbook display.  This is the display your guestbook visitors see first; we’ll come back to it after we add an entry to explain the parameters.  For now, select the Sign the Guestbook icon in the middle left.

 

Figure 4: Sign Book Display is what your users see when they go to sign your guestbook.  If you have smilies and text highlighting enabled, the display will appear similar; if those options are disabled the corresponding areas from the display will not be present.  To add a smilie, the user simply selects the smilie and it is placed in the message area.  To highlight text, the use selects is and presses the B[old], I[talic], or [U]nderline button.  The Characters Remaining field will decrement as each character is typed.

 

The only other field that needs explaining is the Security Code field; a unique code is generated for each entry; the users must supply that code when completing the form to prevent SPAMBots from auto-filling your guestbook.  (Note that you can see the length of the field, or disable it, via the Security tab on the Setup Display).

 

 

Figure 4: Sign Book Display

 

Complete the entry and press the Submit button.  Note: if you took too long to complete the form, the entry will be rejected.  A timer is started when the page is delivered – again, this is to keep automated SPAMbots from constantly filling in entries.  (Note that you can see the length of the timer, or disable it, via the Security tab on the Setup Display).

 

You will be taken back to the Main Guestbook Display, similar to Figure 5: Main Guestbook Display

 

Figure 5: Main Guestbook Display

 

Note that this is the same display your users see when the read the Guestbook, with two exceptions:

1.    Non-Administrator users do not have the Administrator Options selection

2.    Non-Administrator users do not see the yellow option bar on the right side of each guestbook entry.  The yellow option bar is used to add/modify/delete the entries.

 

Let’s explore the Administrator controls (the yellow option bar) for the Guestbook.

 

The  option is used to Edit the Entry (reference Figure 6: Guestbook Entry Edit Display below).  The  indicates the entry is active and visible to all users; selecting that icon will change it to a  meaning the entry is inactive and not visible to all users (Of course, it remains visible here because you are an administrator). A  means the entry was marked a Personal, so only the Admin can see it.

 

The  indicates that either no URL was provided as the user’s homepage, or the homepage is not visible.  You can hover the mouse over it to see the actual value.  Selecting it, if a URL was provided, changes it to a  indicating the user’s homepage is now visible to all users. 

 

Finally the  is used to send email to the user (via your default email client) and the  is used to delete the entry in its entirety. 

 

You will also see a display of the IP Address where the entry came from.

 

The Guestbook Edit Entry display is shown below.  It contains two panes, one for the visitor’s comment and one for the website administrator response.  (If you do not enable Smilies and/or Text Hilighting, your display is minus some of the fields below).  It’s a good idea to press the Preview button when completed, just to ensure your updates are displaying the way you want.  Once your editing is complete, press the Save button.

 

Note that all fields are editable for the Administrator.

 

 

Figure 6: Guestbook Entry Edit Display

 

Creating a Theme

 

Themes are used to customize the look and feel of GreatWebBook to your own website.  If you are artistic, by all means make it your own!!!  If you design a really cool theme, please send it to us at GreatWebScripts and we’ll include it in the next release.

 

To create a theme, create a folder under the /themes directory that is the name of the theme.  In that folder, create a .css file of the same name.  Example: For a theme named “Gumby”, create a folder themes/Gumby that contains a file Gumby.css.   Place your css customizations in that file. 

 

Note that file gwbook.css is included in front of your themefile, so gwbook.css provides the default settings and your themefile overrides those settings.  This also means you do not have to set ALL parameters, only those you want to change.  If you have images that relate to the theme (i.e., background images) create a subdirectory images underneath the themename folder and place the image files in the subdirectory.

 

You may also customize the following images for your themename by placing the appropriate file in the themename folder:

            admin.gif:                              Administrator Options icon [visible only to admin]

guestbook.gif:                                   Sign the Guestbook icon

homepage.gif:                                   Homepage icon on the entry display

texticons/bold.gif:                “Bold” indicator for text

texticons/italics.gif:             “Italics” indicator for text

texticons/underline.gif:      “Underline” indicator for text

 

 

Customizations

 

 In the custom directory of GreatWebBook you will find two files named gwsbook_header_panel-dist.php and gwsbook_footer_panel-dist.php. Use them as a template to create a header and footer for each page of the guestbook (perhaps to use as an advertisement or special notice).

 

To create the included files, copy gwsbook_header_panel-dist.php to gwsbook_header_panel.php and/or gwsbook_footer_panel-dist.php to gwsbook_footer_panel.php, and make any updates in the copied files.

 

You can add smilies by uploading them to the directory indicated on the Admin display.  Simply add them to the directory and refresh the display and the new images will appear.  Conversely, delete smilies by deleting the corresponding gif file from the same directory.  You can find the name of the gif file by hovering the mouse over the smilie name.

 

Tips

 

  1. Review the Activity Log periodically to see if entries are being rejected and the reasons why.

 

  1. If you add words/phrases to your SPAM lists that work well, please notify GreatWebScripts so we can add it to later revisions!

 

  1. Each time you set Encrypt Data Files to Enabled from the security settings, the program generates a new key.  So if you Encrypt -> Decrypt -> Encrypt, you have a different key!!!!  Don’t backup Encrypted Data files. (ref next tip)

 

  1. Backup your data files!!! (gwbook.dat and gwerror.error.txt are the default data file names).  If you encrypt the files, following the following steps:
    1. Set Encrypt Data Files to Disabled;
    2. Backup or copy the data files;
    3. Set Encrypt Data Files to Enabled.

File gwparams.php stores the decryption key --  if you lose it while the files are encrypted, you will not be able to decrypt your data!!!

 

  1. Javascript: For security reasons, many users disable Javascript while browsing the web.  GreatWebBook was designed to not require Javascript enabled to function.  As such, only the ‘extras’ require its use.  If a visitor does not have Javascript enabled while viewing the guestbook, the following anomalies will be noted:
    1. The popup balloon help (from the [?]) will not work.
    2. Selecting a smilie will not add it to the list – instead the user can enter the syntax :smiliename:, where smiliename is the name of the smilie to add (which can be obtained by hovering over the smilie with the mouse)
    3. The character count will not change on the Add form.
    4. The Bold, Italics, Underline, and Color buttons will not work automatically.  The user can type in the correct codes to make them work.