DOCUMENTATION WebBBS 3.21 by Darryl C. Burgdorf (burgdorf@awsd.com) http://awsd.com/scripts/webbbs/ =========================================== WebBBS is, as the name implies, a Web-based bulletin board. Unlike most other such boards, though, WebBBS stores messages as simple text files and creates HTML pages "on the fly." This means that the message index can be tailored by the user based on date and/or subject (via built-in keyword search capability), and can be viewed as either a chronological or a threaded list. It also means that administration is a breeze! WebBBS supports automatic quoting of message text and e-mail notification of those who want to know immediately when a new message has been posted. It also offers an archive-only option and "cookie" support! =========================================== The files that you need are as follows: webbbs.pl: This is the main program file. You don't actually need to do anything to it; in fact, you don't even have to execute it. config.pl: This is the configuration file. Most everything you need to change or modify is contained here. This is also the file that you will execute. (Things are set up this way so that you can effectively maintain multiple discussion boards just by keeping separate config files for each.) webbbs_text.pl: A simple file containing the text of messages included on various pages by the program. They're separated to make alteration or translation a bit easier. (Note that this process is incomplete; much of the program's output text is still contained within the main script. It'll be finished soon.) Basic setup is very simple. You need only to create a directory in which the script will store the BBS files, and make sure that it is set world-writable. All the actual data files used by the script will be created for you. The main program can be put wherever you like. (Just be sure that the configuration file "requires" it correctly.) The configuration script can be placed either in the BBS directory itself (as "index.cgi") or in your CGI-BIN directory, or anywhere else you prefer and your server allows. As noted above, the WebBBS configuration file, and not the WebBBS program itself, should be executed. The configuration file should, of course, be set executable. Make sure that the first line of the script matches the location of your system's Perl interpreter and that the "require" lines point correctly to your main WebBBS script and the text passages script. As well, the following variables need to be defined: $dir: The absolute path (minus a trailing slash) of the directory in which all the WebBBS files are stored. This directory must be set world readable and world writable! $cgiurl: The URL address of the WebBBS configuration script. $UseLocking: Under most circumstances, this variable should be defined as 1. Set it to 0 only if, for whatever reason, your server doesn't support the flock() command. (If this variable is set to 0, a semaphore-based file locking will be used instead of flock(); while it works reasonably well in most situations, it isn't nearly as efficient.) $bodyspec: Any attributes (BACKGROUND, BGCOLOR, TEXT, etc.) which should be assigned to the tag in message posts. $messagespec: This variable functions very similarly to the $bodyspec variable. It should be defined with any attributes you want added to the FONT tags for message texts. $NewCode: This defines the HTML coding you want to use to "flag" new postings. The default value simply places a red "NEW:" in front of the message subject in the index listing. You might want to change it to call a graphic image, for example. $HeadLinesFile: An optional text file containing any HTML code to be inserted within the section of the pages produced by the script. This could include, for example, META tags. $HeaderFile & $FooterFile: Optional text files containing HTML code to be placed immediately following the tag and at the very end of the BBS index page. These are included to allow you an easy way to give your WebBBS index page the same "look" as the rest of your site's pages. This header and footer are used only on the main message index page. $MessageHeaderFile & $MessageFooterFile: Optional text files containing HTML code to be placed immediately following the tag and at the very end of the BBS message pages. You can use the same header and footer on these pages as you use on the index page, or use different ones, or use none at all. This header and footer are used on all individual message pages, configuration pages, and administrative pages. (In other words, they're used on everything *except* the main message index page.) $UseFrames: This can either be set to "horizontal" (or "horiz" or "h") if you want an upper frame for the message index and a lower frame for message texts, set to "vertical" (or "vert" or "v") if you want side- by-side frames, or left undefined if you don't want to use frames at all. $BBSFrame: If you're using WebBBS with frames within another frameset, you'll want to define this with the name of the frameset in which WebBBS is being displayed. (The default definition of "_parent" might also suffice, depending upon your setup.) $WelcomePage: If you're using WebBBS with frames, you can define this variable with the URL of a page you want to appear initially in the WebBBS "message" window (which otherwise will initially be blank). $TopNPosters: If this is defined (with a number), visitors to your bulletin board will be able to access a list showing who's posted the most messages. $Admin_Link_Name & $Admin_Link_URL: You may define these variables with the name and URL, respectively, of an "extra" link you'd like to have appear in the main index page navigation bar. This could be a link to a FAQs or policies page, a link to an archive board, a link back to your main page, or anything else you find relevant. IF YOU ARE USING FRAMES, THIS LINK WILL TARGET THE MESSAGE FRAME, AND NOT THE TOP. Thus, while in that case the link would be appropriate for a FAQs page or other BBS-specific content, it would *not* work very well for a link back to your site's main page. Such links should instead be included in your headers and/or footers. $SepPostForm: If you want the forms for posting new messages included on the main index page and those for posting responses included on individual message pages, then leave this set to 0. If you want those forms to appear on pages by themselves, set it to 1. (Note that if you're using frames, the forms will *always* appear on separate pages, regardless of how you've set this variable.) $DefaultType: By design, WebBBS index displays default to a simple chronological display. If you prefer a different style, define it here. The available options are "Chronologically", "Chronologically, Reversed", "By Threads", "By Threads, Reversed", "By Threads, Mixed", "Compressed", "Compressed, Reversed", "Guestbook- Style", "Guestbook-Style, Reversed", "Guestbook-Style, Threaded", and "Guestbook-Style, Threaded, Reversed" $DefaultTime: This variable sets the default for the age of messages shown in the index list. If left unspecified, the index will display messages posted within the past week. Valid values are "Twelve Hours", "Day", "Two Days", "Week", "Two Weeks", "Month", and "Archive". The latter instructs WebBBS to display *all* messages. $boardname: The name of your specific discussion board. THIS VARIABLE MUST BE DEFINED FOR COOKIES AND CERTAIN OTHER SCRIPT FUNCTIONS TO WORK PROPERLY! If you don't want the board name to print, set $printboardname as 0. Do *not* simply leave $boardname undefined. $printboardname: If this variable is set to 1, the board name defined above will be included at the top of the script-generated pages. If the variable is set to 0, it won't be. This allows you to avoid duplication if you're using a graphic image in your header, for example, as a title. $DateConfig: A string defining the format in which you want dates to appear on the board. The following codes are available: %mo% = month (numeric) %MO% = month name (as defined in webbbs_text.pl) %dy% = day of month (numeric) %DY% = weekday (as defined in webbbs_text.pl) %yr% = year (two-digit) %YR% = year (four-digit) %am% = either "a.m." or "p.m." %sc% = seconds (two-digit) %mn% = minutes (two-digit) %hr% = hour (12-hour clock) %HR% = hour (24-hour clock) So, for example, "%mo%/%dy%/%yr% %HR%:%mn%" would display dates as "7/22/98 15:30"; but "%DY%, %dy% %MO% %YR%, at %hr%:%mn% %am%" would display as "Wednesday, 22 July 1998, at 3:30 p.m." $IndexEntryLines: This variable defines the format in which the index should be displayed. Defining it as 1 gives each entry a single line, while defining it as 2 gives each entry two lines. (The latter is the better bet if you're using a longer date format and/or displaying extra information such as IP addresses or view counts.) You can also define the variable as "news" in which case the index will be displayed in a tabular format similar to that utilized by many Usenet newsreaders. $InputColumns & $InputRows: These variables define the size of the text input box for messages. The default size is 80 columns by 15 rows. The smallest allowable size is 25 columns by 5 rows. $HourOffset: If you are in one time zone and your Web host is in another, you can use this variable to adjust the times shown for posts on your BBS. For example, if your server is located in the Eastern time zone, but you're in the Pacific time zone, set it to "-3". $ArchiveOnly: If this variable is set to "0" the board will function normally. However, if it is set to "1" the message posting form will not appear either on the index page or on individual message pages. This allows you to set up a "read-only" archive board. (As a side note, if you move files to a new directory from your active board to set up such an archive, be sure to use the UNIX "mv" command rather than the "cp" command. This will insure that the file modification dates are not altered, so that searches by date will work!) If you enable the admin functions (see below), the administrator will be able to post even to a "read-only" board. This allows you to set up "announcement" boards to which you and only you can post. $AllowHTML: If this variable is set to "1" people posting messages will be able to embed HTML tags (hyperlinks, image references, formatting commands, blinking text, etc.) in their messages. If it is set to "0" they will not be able to do so. Be aware that allowing embedded HTML virtually invites abuse of your bulletin board. Setting the variable to "2" will allow any HTML codes to be displayed in the message rather than being either interpreted or stripped. This can be handy, for example, if the subject of your BBS is how to code HTML. SSI commands will *never* be interpreted by the script. If this variable is set to "2" they will be displayed along with any HTML tags; otherwise, they will simply be stripped. $SingleLineBreaks: WebBBS automatically recognizes a double line break or an indentation (either a tab or multiple spaces) as the start of a new paragraph. If this variable is set to "0" any single line breaks will be ignored. If it is set to "1" any single line breaks will be converted to
tags. The former option is usually preferable if most posts consist of straight text. If, however, those posting on your board frequently post itemized lists, you may want to use the second option, to allow more accurate formatting. $AutoQuote: If this variable is set to "1" the new text of a message will automatically be quoted in the message response input box. If it is set to "0" the box will be empty. $AutoQuoteChar: This defines the character you want used at the beginning of "quoted" lines. $AutoHotlink: If you set this variable to 1, the script will attempt to "automatically" hotlink any URLs included in the body of a message. $DisplayIPs: If this variable is set to 1 or 2, posters' IP addresses will be displayed along with their names and e-mail addresses. (Note that IP addresses are recorded in the message files and message index for the administrator's reference, regardless of whether or not they're actually displayed to visitors.) If it is set to 1, the script will attempt to resolve IP addresses to host names; if it is set to 2, the script will simply record the "raw" IP numbers. $DisplayViews: If this variable is set to 1, the script will keep track of and display in the index the number of times each message has been read. It's a nice feature, but especially on busy boards, turning it on can *drastically* affect system performance, as the message index database has to be rewritten each and every time a message is read.... $UseCookies: If this variable is set to "0" (or commented out) the use of "cookies" will not be implemented. If it is set to "1" it will be. "Cookies" allow the board to recognize return visitors, keep track of messages posted since their previous visit, maintain their personal index display preferences, and automatically insert their names and e-mail addresses into the post forms. IN ORDER FOR "COOKIE" SUPPORT TO WORK, you must first install Matt Wright's "cookie.lib" (available from ). If you're not using "cookie" support, comment out the "require" line in the configuration script. Otherwise, make sure it points to the correct location on your system of Matt's "cookie" library. $Max_Days & $Max_Messages: By setting one or both of these variables, you instruct WebBBS to automatically purge message files for you. (This is the "reaper" function mentioned above.) For example, if you set $Max_Days to "7" any messages which have been sitting idle for over a week will be deleted, and if you set $Max_Messages to "200" you will never have more than 200 messages in your index. If you set both variables, older messages will be deleted first, and then more recent messages will be deleted if necessary to bring the total number within your prescribed limits. Note that on some servers, having more than about 2000 files in a single directory can cause system problems, and that on *any* server, having that many files is at least likely to slow things down a bit. So as a general rule, $Max_Messages should *always* be set, and should usually not be set higher than 1500 or so. $ArchiveDir: If instead of being deleted, you want "expired" messages to be moved into another directory (for example, for use in a "read- only" archive board), define this variable with the full path to the directory in question. This will replace the "reaper" function with a "harvester" function, which will remove the old messages from your active board by moving them rather than by deleting them. Please note that when you remove messages from the data directory, they are no longer available on the message board at all! (That is, after all, the whole point!) If you want "archived" messages to be available, you need to specifically set up a *second* WebBBS implementation (presumably in "read only" mode) utilizing the archive directory as its data directory! $MaxMessageSize: This is the maximum size (in kilobytes) of messages which can be posted. The primary purpose of this variable is to prevent users from posting entire book chapters or the full text of long CGI scripts.... $MaxInputLength: This variable defines the maximum length of message subjects and author names. $LockRemoteUser: If your WebBBS script is password protected via .htaccess or another system which sets the "REMOTE_USER" environment varaible, you can elect to force users to post under their login names by setting this variable to 1. $AllowUserDeletion: Set this to "1" if you want users to be able to include a password with their messages which will allow them to come back and delete them on their own. Leave it undefined if you want them to be stuck with what they posted. $AllowEmailNotices: Set this to "1" if you want users to be able to request e-mail notifications whenever someone responds to their messages. Leave it undefined if you want to require them to actually visit the BBS again to find out. This ONLY defines whether or not people can request automatic notifications of responses to their own posts, and is distinct from the $email_list variable (below), which defines what, if any, new post "subscription" capability your board will support. Like the other e-mail functions, the automatic notification of responses will be disabled if you do not define the $mailprog variable. $AllowPreview: Set this to "1" if you want your users to be able to "preview" their posts before actually submitting them. $AllowURLs: Set this to "1" if you want users to be able to include a URL link at the bottom of their messages. (This can be handy if you don't allow HTML in posts, and can even be nice if you *do* allow it.) $AllowPics: Set this to "1" if you want users to be able to include a link directly to a graphic image on their own or another server. Depending upon the nature of your BBS and the demographics of your audience, of course, you very well may not want them to be able to post unapproved graphics.... $SaveLinkInfo: If you set this variable to 1, any information provided in the optional link and image fields will be stored in the user's cookie file. If you have a lot of people who use those fields for a sort of "signature," you'll probably want to turn this feature on. If, on the other hand, most of your users only fill out those fields with information relevant to a specific post, you'll want to keep it turned off. $AllowUserPrefs: If you set this variable to 0, users will *not* be able to alter the style in which messages are displayed. (They will, of course, still be able to search for specific messages.) $AllowResponses: If you set this variable to 0, users will only be able to post new messages; posting follow-ups (responses) to existing messages will not be possible. This is useful if, for example, you're setting up a "classified ads" system, and don't want visitors to be able to respond publicly to the listings. $NaughtyWords: If you want certain words to be "censored" in posts to your BBS, simply list them here (separated by spaces). $CensorPosts: If this variable is set to 1, any words (or character strings) matching the contents of the $NaughtyWords variable will be replaced by a string of hash marks in the actual post. For example, if you defined $NaughtyWords as "this that" and someone attempted to post the message, "This is one thing, that is another," the actual post would appear as "##### is one thing, ##### is another." If you leave this variable set to 0, a message containing forbidden words will not be posted at all; instead, the poster will be shown a message stating that his message was rejected for content, and will be given the option to go back and "clean up" the post himself. $BannedIPs: If you want certain individuals to be "banned" from posting to your board, list their IP addresses and/or host names (separated by spaces) here. Partial addresses are OK, but note that *anyone* whose IP address includes the "forbidden" string will be banned. NOTE THAT IT IS VERY DIFFICULT TO SUCCESSFULLY BAN SOMEONE; the sad truth is that if you start banning IP addresses, you're far more likely to end up banning innocent bystanders than to successfully get rid of a troublemaker. $mailprog: The absolute path to your system's sendmail program. (Note that this is *not* the same as the "mail" program, and has absolutely nothing to do with Matt Wright's "formmail" or any other CGI script.) If your system doesn't have "sendmail," you can instead define the variable as "SMTP" to instruct WebBBS to access your server's mail server directly. (The former is preferable if available, of course, as it's more efficient.) If you simply don't want the various e-mail notification functions activated, leave this variable unassigned. $WEB_SERVER & $SMTP_SERVER: If you're using a direct SMTP interface, you can define either or both of these variables with the relevant server names. If you leave them undefined, the script will attempt to determine for itself what the names should be. If you're using sendmail, of course, these variables are irrelevant. $admin_name: The name of your board's administrator. It will appear at the bottom of script-generated pages with an e-mail link (using $maillist_address, below). $maillist_address: The address you wish to use for e-mail related to your BBS. The "@" character in your address must be "escaped" with a backslash (e.g., "scripts\@awsd.com"). Note that this variable should be assigned even if you don't enable the various e-mail notification functions, since the maillist address is also shown on some of the BBS's admin pages to let people know how to contact you if they have any problems. $notification_address: If you send out e-mail notices, they will be addressed "From:" the $maillist_address above, and "To:" the address defined here. If you don't want to receive copies of all the notices, define this with a dummy value. If you *do* want to receive copies, define it with a real address (such as your administrative address already defined above). Please note that by "dummy value" I do *not* mean that you should send the notices to someone else's domain! Set up an address within your own domain which automatically deletes incoming mail! $email_list: If you don't want to set up any sort of e-mail list to notify interested parties of new posts, simply leave this variable unassigned. If you have a relatively low-volume board, and want to allow people to get e-mail copies of any messages immediately as they are posted, set it to "1". If you want to set up a digest-style notification list, set it to "2". Note that the digest mailings are *not* handled by the WebBBS script itself; if you want to send out that sort of notification, you'll also need to set up the separate WebBBS Digest script available from the WebBBS "Examples and Extras" page . $private_list: If you want e-mail notices to be sent out, but *don't* want just anyone visiting your board to be able to subscribe, set this variable to 1. (Setting this variable to 1 but leaving $email_list set to 0 is an easy way to ensure that the administrator gets copies of each post, even if no one else does.) $HeaderOnly: If you set this variable to "1", any e-mail notifications will contain only the header information, and not the main body of the post. This is handy if you want to be able to let people know when new messages are posted, but still want them to have to come to the BBS itself to *read* thos messages. Note that this setting will not effect the manner in which digests are sent out; if you're using the digest option, the e-mail notices will *always* contain the full text of the messages posted. FINALLY, if you're using Perl 5 rather than Perl 4, *and* are utilizing the direct SMTP interface rather than the "sendmail" program, uncomment the "use Socket" line in the config file. (In other words, remove the initial hash mark symbol.) Otherwise, just leave it alone. =========================================== E-MAIL NOTIFICATION LISTS Although WebBBS can handle fairly large e-mail notification lists, you'll probably find as your board gets busier that your subscribers don't like getting lots and lots of individual message notifications. If you're running a board with heavy traffic, you should probably switch from the basic "as messages are posted" notification scheme to the more efficient digest setup. (As noted above, the digest mailings are *not* sent out by WebBBS itself; they are handled through the separate digest script, available from the WebScripts site, which can easily be set via cron to run automatically at regularly-scheduled intervals.) =========================================== WEBBBS SECURITY Though WebBBS does not yet directly incorporate password protection, it works quite well with server-based protection. All you need to do is locate your configuration file in a password-protected directory. And if your security system sets the "REMOTE_USER" environment variable, as most do, you can even set WebBBS to require that users post under their login IDs, thus preventing them from posting under someone else's name. Even if you're not password-protecting your BBS, you should still either password-protect your data directory, or locate it outside of your Web space. There's no need for the directory itself to be accessible to the public, and you're probably better off if it isn't. (NOTE that the directory *does* need to be set world-writable, as stated above; what I mean here is that it doesn't need to be physically located within your Web space. The script needs to be able to read its contents, but your visitors don't!) If you want to set up a board which anyone can read but to which only a few designated people may post, you can easily do so by setting up two configuration files for the same data directory. One would be publicly accessible, but defined as "read only"; the other would allow posting, but be accessible only to those with appropriate IDs and passwords. =========================================== USING WEBADVERTS WITH WEBBBS If you're using WebAdverts to display advertising banners on your site, and want to display banners on your BBS pages as well, you'll need to define the "require" line and the first two variables ($adverts_dir and $display_cgi) in the "insert adverts" subroutine at the end of the configuration file to match the same lines in your WebAdverts configuration file. Once that is done, you can include banners anywhere in your header or footer files simply by insert the comment line "" wherever you want a banner to appear. Note that the zone name itself is optional; if you want a banner displayed without regard to zones, or if you're not using zones, you can leave out the specification. =========================================== REGISTERING WEBBBS: WebBBS is shareware. If you use it, please register it! The registration fee is only $50 (US). Payment should be sent via check or money order to Darryl C. Burgdorf, Affordable Web Space Design, 3524 Pacific Street, Omaha NE 68105. (If you happen to live in a country other than the United States, you can write a check in your local currency for the equivalent of $57.50. That will cover the $50 registration fee and the $7.50 service fee which my bank charges. Please do *not* write me a check in US funds drawn on a non-US bank; the service charge for those can be anywhere from $10 to $25!) The unregistered version of the script is not crippled in any way. I'm not trying to "coerce" anyone into sending me money. But I don't think it's an unreasonable request. I believe WebBBS is a commercial- quality product; a *lot* of work has gone into its creation. If you use it, I'd appreciate it if you would be kind enough to send in the registration fee. I'll be that much more likely to be able to continue spending time and effort on the scripts in the WebScripts collection, and you'll have the satisfaction of knowing you did the right thing. ;) As well, as a registered user of the script, you'll be able to download and utilize the WebBBS administrative maintenance script, which, while not strictly *necessary*, will probably make your life easier. =========================================== This documentation assumes that you have at least a general familiarity with setting up Perl scripts. If you need more specific assistance, check with your system administrators, consult the WebScripts FAQs (frequently-asked questions) file , or ask on the WebScripts Forum . -- Darryl C. Burgdorf