My article on XP's Windows Error Reporting system for O'Reilly's WindowsDevCenter.com was targeted towards end-users, so a developer section on how to get crash reports on non-XP systems didn't really fit. Still, it's interesting for developers, so here is the section that was cut. For background, please refer to the published article.
Crash Reports on non-XP Systems
WER was introduced with Windows XP, and also runs on Windows Server 2003. The system files that implement WER are not redistributable because they rely on kernel and global exception handling code that is specific to XP. Microsoft will support WER on future versions of Windows, but has no plans to retrofit it for older versions. The reason that Office XP and Explorer can produce crash reports on back versions of Windows is that they use a custom crash report system that pre-dates WER.
Developers writing for older operating systems can't use WER for crash reports, but they can use an elegant replacement called XCrashReport, written by software consultant Hans Dietrich. XCrashReport was published on Code Project in a series of four articles. The first article describes how to find bugs using release-mode crash reports. The second and third describe some additional techniques. The fourth article contains the utility for generating crash reports and prompting users to send them back to the developer:
http://www.codeproject.com/debug/XCrashReportPt1.asp
http://www.codeproject.com/debug/XCrashReportPt2.asp
http://www.codeproject.com/debug/XCrashReportPt3.asp
http://www.codeproject.com/debug/XCrashReportPt4.asp
XCrashReport uses a redistributable, backward-compatible XP library called dbghelp.dll to produce mini-dumps. It also captures exception information, register values, stack data, and a list of the modules loaded at the time of the crash (all data that WER collects as well). Programmers can optionally add to the report any registry keys that might help diagnose the cause of the crash. End-users can review the contents of the error report files before deciding whether to submit them.
If the user agrees to send the crash report, the files are zipped up and sent through unencrypted email directly to the software developer. They are not added to the WER database on Microsoft's server. Some end-users may feel more comfortable sending the files directly to the programmer, but as you'll see in the next section, there are some compelling advantages for both the end-user and developer to using Microsoft's tightly protected, carefully monitored, and usefully organized central repository.
XCrashReport isn't suitable for use with programs that have a large user base since the number of XCrashReport emails that a company receives could quickly become overwhelming. But for small developers writing software for pre-XP versions of Windows, XCrashReport is a good solution. Also, shareware developers operating on a budget will be relieved at not having to purchase a VeriSign ID (a requirement for accessing the WER system).
The Web Log you are now reading was created with a server-based publishing system called Movable Type. Installing server-based software isn't difficult, but it requires many more manual steps than installing a program on your local computer. Before you can run an installation script, you must first put the files in the correct places on the server, set the correct permissions, manually create any necessary databases, and correctly specify configuration parameters.
This is not hard to do if the software comes with precise, complete, and clearly written instructions. But unfortunately, the Movable Type installation docs are not as good as the software itself. So my first blog entry is a tutorial on how to install Movable Type, focusing on the parts that were unclear to me when I was doing it.
My installation of Movable Type is on a Linux server with a MySQL database. If there are issues with other operating systems or databases, they won't be addressed here. But most of what I describe here will be relevant across platforms.
I'll start with a list of what files go where (a directory structure that works) and the necessary permissions for the various files. Don't forget to upload files in the correct mode:
- Everything except the bitmaps must be uploaded in ASCII mode.
- The bitmaps must be uploaded in BINARY mode.
If you don't upload things in the correct mode, the scripts won't run and the bitmaps won't display.
Directory Structure
You will have two Movable Type directories, one containing the program and the other containing the data (your blog entries, and the Movable Type documentation and bitmaps). You need two directories because only script files can go in cgi-bin. Files stored in cgi-bin cannot be viewed or downloaded by visitors, only executed. Don't be tempted to put the entire installation outside cgi-bin because the limitations are a security feature.
The directories listed below are described relative to the Web site's home directory. For example, the directory /cgi-bin/ corresponds to a URL like http://www.domain.com/cgi-bin/. When you configure Movable Type, you will need to know the server path to this home directory. If this information isn't in your server's control panel, ask your Web host administrator what it is.
Beneath each directory name is a list of what it contains, followed by notes.
Program directory: /cgi-bin/movabletype/
- all files with this filespec: mt*.cgi
- the configuration file: mt.cfg
- these folders: extlib, import, lib, schemas, search_templates, tmpl
Notes:
Set the permissions for all the CGI files to 755.
The "import" directory is something you create; it's not in the distribution zip.
The "extlib" directory will only contain extensions not already installed on your server, so don't upload any files or folder to this yet. Just create an empty directory with this name and read on.
Data directory: /movabletype/
- these folders (you manually create them): archives, mt-static
Notes:
The /movabletype/ directory is where current blog entries are stored. Archives are stored in /movabletype/archives/. The Movable Type documentation and bitmaps are stored in /movabletype/mt-static/.
The folders containing blog entries must be writable by the world, so the permissions for /movabletype/, /movabletype/archives/, and all the files within these folders must be set to 777 (full permissions), unless you have special security software running on the server. See the Movable Type documentation for details.
Movable Type docs and bitmaps: /movabletype/mt-static/
- these files: index.html, style.css
- these folders: docs, images
Notes:
The index.html file is mainly there to prevent visitors from viewing the contents of this directory. There is a link on this page to the Movable Type documentation.
The Two Files You Need to Edit
There are two configuration files you will need to edit:
- mt.cfg
- mt-db-pass.cgi
To configure your settings, you need to know:
- server path to your home directory
- server path to your sendmail program
- server path to Perl
- if there is anything in your MySQL installation that differs from the default
If this information isn't listed in your server's control panel, ask your Web host administrator.
The other thing you need to do before editing the configuration files is create an empty MySQL database (call it MovableType), and set up a username and password with full permission to access it. Don't use the same username and password you use to access your Web hosting account; set up a separate one.
Once you have all the information and have created the MySQL database, you are ready to edit mt.cfg. The comments in the file explain almost everything, with the exception of the database settings, which are described in the Movable Type installation docs.
The database section is near the top of the file and contains just one line: "DataSource ./db". Since you will be using a MySQL database, comment out this line (put a # sign in front of it) and add these three lines in its place:
ObjectDriver DBI::mysql
Database database_name
DBUser database_user
Replace database_name and database_user with the names you set up when you created the database. If you called your database MovableType as I suggested above, the database line will read:
Database MovableType
If your MySQL installation is different from the default in terms of hostname, port, or location of mysql.sock, then you will need one or more of these additional lines (default settings are shown here):
DBHost localhost
DBPort 3306
DBSocket /tmp/mysql.sock
After you've finished editing the database settings, go through the rest of mt.cfg slowly and methodically. Read each comment carefully and make a choice; do not skim. If you want the default setting, leave the line for that setting commented out. You only need to uncomment lines when you are changing the default.
When you're done editing mt.cfg, there is only one more change you need to make: edit the file mt-db-pass.cgi. This file contains a single word, "database_password", and nothing else. Replace "database_password" with your MySQL password. The password is stored in a separate file for security reasons.
Upload the two edited configuration files to the program directory on the server. If you uploaded these files before and set their permissions, you don't need to set them again.
How to Know Which of the extlib Files You Need
The files and folders in extlib are extensions that you may already have on your server. You only need to install the ones you don't have. To find out what you need, point your browser here: http://www.domain.com/cgi-bin/movabletype/mt-check.cgi. This script will check your server, and tell you which extension modules are missing.
In addition to what this script reported, I had to upload the subdirectories "I18N" and "Locale". I got error messages when they weren't there.
Run the Installation Script
Now all the files you need are on the server in the correct places, the correct permissions have been set, and the configuration parameters have been specified. So point your browser to this URL:
http://www.domain.com/cgi-bin/movabletype/mt-load.cgi
This script creates the initial Movable Type files, and sets up the database tables. After you have successfully run mt-load.cgi, delete it from the server. It is a serious security risk not to do this.
Configure Movable Type
Now you are ready to log into Movable Type for the first time so you can configure it. Point your browser here:
http://www.domain.com/cgi-bin/movabletype/mt.cgi
This is the administration area. Log in using the default username (Melody) and password (Nelson).
There are two configuration changes that are necessary. Everything else is optional:
- Edit the profile to change the username and password (that's for security).
- Edit the paths. For some reason, Movable Type does a poor job of guessing and they will be wrong. In general, the string "cgi-bin" should not be in there anywhere.
Now you have a working blog, though you will probably want to change the default appearance and settings. Most of the settings are clearly documented within the program except for the Templates area, which controls the appearance of your blog.
The style presets are not stored within the program itself. They are on the Movable Type Web site here:
http://www.movabletype.org/default_styles.shtml
Copy the style code you want from this page, then paste it into the edit box on the Templates page.
Before you make your blog live, test all the links. It's very easy to mess up the paths.
I hope this overview is helpful and saves you some time.