The Bosco Web Server

(18 January, 2012)


Introduction

  Bosco is a computer program built to operate as a web server for Windows operating systems. Bosco is logically equivalent to the Microsoft Internet Information Server (IIS) and other servers such as Apache.

A good question would be: why create yet another web server? After all the IIS and Apache are competent, full featured server implementations. The answer is simple. Well, actually, simplicity and reliability is the answer. Bosco's design and implementation was kept simple so the possibility of security problems would be minimal. Bosco is built to resist hacker break-in attempts.

Additionally, Bosco's setup and operation were designed to be simple. Simple configuration settings minimize the chance that a Bosco installation will be accidentally setup in an insecure manner. As with any web server, Bosco can be made insecure by using inappropriate configuration settings. Bosco's setup is clear and concise to help prevent configuration errors.

As for the question, why is it named Bosco? Well, that was the name of a programming project I had started long ago and never finished. "BOSCO" was kind of acronym for the project's function. I have no clue now how I came up with that as it makes no sense to me now. When I started building a web server, I recycled that old project directory. That's how Bosco got its name.


Major Features

 
  • Small and Simple: Unlike the IIS and Apache, Bosco is compact and easy to configure. The entire Bosco executable program is under 150 Kbytes. Only two other small configuration files are needed. Only 3 or 4 text lines are needed to define the configuration of a small Bosco web server installation.
  • Hacker Proof: Bosco was specifically designed to survive web hacker break-in attempts. Though no server software can ever guarantee absolute protection from break-ins, Bosco's simple internal design minimizes the possibility that hackers will be able to find a security flaw I overlooked.
  • High Performance: Though high performance was not one of its design parameters, Bosco performs very well under heavy user loads. Bosco may be configured to handle a continuous load of up to 256 simultaneous HTTP requests. That is not simply 256 simultaneous users. It is 256 users clicking a link to a new page at the same instant. The default configuration is 100 simultaneous requests. Bosco easily exceeds the performance of IIS and Apache.
  • User Authentication: Bosco supports user ID and password protection of directories when needed.
  • CGI Support: Bosco supports the use of CGI server extensions. CGI data input and output is buffered to block hacker access to operating system tools.
  • ISAPI Support: ISAPI server extensions are supported. Bosco loads ISAPI extensions at startup and does not unload them until shutdown to assure that only those specifically defined in its configuration file are used.  

Setup

  Bosco's setup is simple. Setting up Bosco for the first time should take no more than a few minutes. The steps are:

1. Unzip the Bosco Files

Bosco is distributed as a ZIP file. This file contains the Bosco server executable, example configuration files, and some "readme" files to help you get started.

Use PKUNZIP or WINZIP to decompress the files into a convenient directory. If this is the initial setup of Bosco, I would recommend you create a separate directory for Bosco. The name of the directory does not really matter but I suggest you use the name "bosco". (i.e. c:\bosco).

The three files you are really interested in are "bosco.exe", the server program, "bosco.conf", the configuration file, and "mime.conf", the HTTP mime type definitions. You will be editing the contents of "bosco.conf" to configure your Bosco installation. Bosco configuration entries are discussed in detail below. You will probably not need to edit "mime.conf".

2. Verify Directory Configuration

Bosco may be installed in just about any directory though using something simple like "c:\bosco" is probably a better choice. The two configuration files, "bosco.conf" and "mime.conf" must be placed in the same directory as "bosco.exe". Additionally, there must be three subdirectories created in that directory. They are named "logs" "sec" and "temp".

An example directory layout might be:

C:\ (The root directory)
<bosco> (The C:\bosco directory)
<logs> (The C:\bosco\logs log directory)
<sec> (The C:\bosco\sec security directory)
<temp> (The C:\bosco\temp Bosco temporary files directory)
bosco.conf (The Bosco server configuration file)
bosco.exe (The Bosco server executable)
mime.conf (The HTTP mime data type definitions)

The "logs" subdirectory is where Bosco creates its log files. There are two log files: "access.log" for logging access to files and "error.log" for logging operational errors. Logs are discussed in more detail below.

3. Edit the "bosco.conf" Configuration File

Bosco's configuration file, "bosco.conf" is an ASCII text file that may be edited with any convenient text editor such as "notepad". A complex configuration is typically contains only about 15 or 20 entries, one text line per entry.

The minimum configuration file content that may be used is 3 entries. As an example, assume your web server is named "www.myservice.com" and your web pages are stored in your "c:\web" directory:

ServiceName = www.myservice.com
Directory
Path = c:\web

The above example will work just fine but there are a couple things you might want to add such as defining what file should be returned by default if no filename is specified in the request, and maybe whether you want to allow access to files that are in subdirectories of "c:\web". These and many other available features are discussed below.

4. Start the Bosco Server

Starting Bosco is simple too. Open a DOS console window. Change directory to to where you installed "bosco.exe". That would be the "c:\bosco" directory in the example above.

Type the following command at the DOS prompt:

bosco

Bosco will attempt to start. Progress messages will be written to the screen. If some error prevents Bosco from successfully starting, information about that error will be written before Bosco aborts the startup. You may also examine Bosco's startup messages to verify that your configuration file settings are properly interpreted.

Critical internal operational errors will be written to the console screen. Web request access and error logging will also to be written to "access.log" and "error.log".

Stopping Bosco is done by hitting Control C. (i.e. holding down the "Ctrl" key and tapping the "C" key.)


Configuration Basics

  One of the more important targets in Bosco's design was operational simplicity. No matter how robust the program code inside Bosco might be, service security can be compromised by configuration errors. Making configuration of Bosco simple, succinct, and clear is critical.

Bosco uses two configuration files: "bosco.conf" and "mime.conf". Both of these files consist of sequences of ASCII text lines. Of these two, "bosco.conf" is probably the only file you will need to work with. "mime.conf" provides entries for a simple table that equates file extensions with HTTP mime data types.

"bosco.conf" consists of main sections: service wide definitions, and file directory specific definitions.

Service Wide Definitions

The service wide configuration definitions are placed in the "bosco.conf" before any directory specific definitions. The service wide configuration items are:

  • ServiceName (required)
  • Port
  • RcvTimeoutSeconds 
  • ServiceThreads
  • CgiTimeoutSeconds
  • EnvPassThru

These entries are discussed in detail below. Notice that only "ServiceName" need be supplied. The remaining values default to safe values.

Note: Most of the directory specific configuration entries may also be placed in the service wide configuration area also. When this is done, the values supplied will be used globally for all directories defined later in the file unless overridden by entries in individual directory definitions. 

Directory Specific Definitions

Each directory served by Bosco must be defined in "bosco.conf". A directory definition begins with a text line with the single word "Directory". The values associated with that directory follow that line and apply to that single directory until another "Directory" line occurs.

The directory specific configuration entries are:

  • Path (required)
  • Name
  • DefaultFile
  • BasicDomain
  • AllowSubdirectories
  • AllowDirList
  • LogImages
  • LogAccess
  • LogErrors
  • Log404
  • SetExtension
  • AllowExtension
  • SingleThreadCGI
  • AllowCgiCmd

These entries are discussed in the sections below.

Note: All of the directory specific entries except for "Path" and "Name" may be used in the service wide section of "bosco.conf".

Entry Format

All "bosco.conf" entry lines with the exception of the "Directory" line, use the following format:

<entry-name> = <entry-value>

For example, the path entry for a directory would be written as:

Path = c:\web

The example above describes the physical path for the virtual directory being defined as being as "c:\web".

Comment Lines

Comment lines may be used in "bosco.conf". Comment lines are denoted by beginning them with a "#" (pound sign) character. Any text line in this file that begins with the "#" character will be ignored by Bosco.


The Simplest Configuration

  Web sites which serve just a single directory of web pages and images can be described with just four configuration entries. From the site wide group of entries, we must supply the "Name" entry. We must supply a line containing the single word "Directory" to tell Bosco to define our default directory. We must then supply a "Path" entry to tell Bosco what physical directory to serve. Though it is not required, we should also define a default file to be returned to users that access the web site using just the service name and no filename.

The "bosco.conf" file would contain the following lines:

ServiceName = www.myservice.com
Directory
Path = c:\web
DefaultFile = index.htm

Of course, you would substitute the real name of your server, the real directory name, and the real default filename.


Service Wide Configuration Entries

 

This section contain entries that are service wide in scope:

ServiceName
(required)

This is the Internet DNS name of this service.

Example:
 ServiceName = www.whatever.com
ServicePort
(optional)

This is the TCP port number of the service. The standard port number for Internet web servers 80. If you do not include this entry in "bosco.conf", Bosco will use port 80.

Example:
 ServicePort = 80
ServiceThreads
(optional)

This is the number of simultaneous web requests Bosco is to handle. The range allowed is 20 to 256. Smaller numbers use less system memory and other resources. Larger numbers handle heavier loads. 20 is typically adequate for most light duty small business uses. 100 is adequate for most applications. The default value is 100.

Example:
 ServiceThreads = 100
RcvTimeoutSeconds
(optional)

this option allows you to set how log Bosco should wait for network packets while receiving requests. The range allowed is 5 to 60 seconds. 5 seconds is adequate for most connections. Longer times allows for extra slow browser connections.

Example:
 RcvTimeoutSeconds = 30
CGITimeoutSeconds
(optional)

This option allows you to set how long Bosco should allow a CGI script to run before killing it. By default, Bosco allows 300 seconds (5 minutes). Usually, if a CGI script runs for more than a few seconds before returning control to Bosco, it is locked up and should be killed. If some other time span is desired, use this option. Default value is 300.

Example:
 CGITimeoutSeconds = 300
EnvPassThru
(optional)

This option is used with CGI Scripts. Most small business CGI script applications do not need the use of this option. By design, Bosco does not supply any of the WIN32 environment variable data to CGI scripts. In rare cases, however, scripts are written to use one or more entries from the WIN32 environment. This option is used to specify the names of those entries. Multiple entries are specified by including more than one EnvPassThru lines in Bosco.conf. You repeat this option line as many times as needed.

Example:
 EnvPassThru = WINNT

Directory Specific Configuring Entries

 

A simple Bosco installation actually needs only one directory defined. That directory is the site's default file directory. It is common, however, for sites to have additional directories defined to allow separating HTML web pages, images, and CGI scripts into separate directories with different permissions and attributes.

Files served by a web server are referenced not only by name but by which file directory they reside in. The obvious exception, of course, is for the default directory. Most web sites are set up to provide access to some default directory if no directory path was supplied in the Browser's URL line. In most cases, web directories are set up provided a default file if none is specifically requested. That is to say, supplying a browser with a URL that reads "http://www.ibm.com" will typically cause IBM's main web site to return the contents of some welcoming page from a default file directory.

File directories in Bosco, as with essentially all other web servers, are "virtual" directories. That is, the names of these directories when used in URLs have little or no relationship to their physical location or name in the server. For instance, a file with a URL like "http://www.microsoft.com/images/logo.gif" might actually correspond to "c:\default_site\corporate_images\logo.gif" 

There is one unique case for directory naming. Your default directory configuration will have a "Path" entry but will not have a "Name" entry. That is how Bosco determines that a default directory is being defined. All other virtual directories must have both a "Path" entry and a "Name" entry.

Remember that a directory definition begins with a text line with the single word "Directory". The values associated with that directory follow that line and apply to that single directory until another "Directory" line occurs.

Directory
(required)

There is one entry that has no parameter. That is this one. A line with the word "Directory" marks the beginning of a directory definition.


Path
(required)

This is the physical disk directory to be used.

Example:
Path = D:\www
Name
(required except
for default
directory)

This is the name web browsers will use to access files in the directory described in the "path" parameter for this directory.

Example:
 Name = images

This name need not be similar to the directory referred to in the "path" parameter. This name may contain subdirectory style formatting to provide a directory structure view to Internet users that has no relationship to the actual physical directories used.

Example:

Directory 1:
 Directory
 Name = cat
 Path = C:\MyDocuments\FelineStuff
Directory 2:
 Directory
 Name = cat/tail
 Path = D:\furry\appendages

In the case of Directory 2, Bosco would check an incoming request URL for matches in your directory definitions and notice that "cat/tail" is a defined directory and not just a subdirectory in "cat".


DefaultFile
(optional)

This option allows you to specify the name of a file, typically an HTML welcome page, to be returned if no specific page was requested. This feature of web servers is often used to supply an HTML welcome page. Typical values are "index.html" on UNIX systems and "default.htm" on WIN32 systems. No default value is provided.

Example:

 Defaultfile = index.html

Configuring Logging

  By default, Bosco logs all requests received and all errors it detects. Requests are logged in a file named "access.log". Errors are logged in a file named "error.log". Both files may be found in the Bosco "logs" subdirectory.

A common problem encountered with busy web sites is that the volume of log entries is so high that it is difficult to distill useful information from them. Bosco includes provisions for eliminating the logging of selected events if desired. This may be done on a directory-by-directory basis.

You may disable logging of requests for files in a directory or just image files in a directory. You may disable logging of errors or just "404 - Object not found" errors. 

LogImages
(optional)

(YES/NO) This option allows you to turn off logging of requests for image files. Many graphics rich web sites contain many images on each HTML page. Access logs grow large rapidly if image access are logged on these sites. Default is YES

Example:
 LogImages = NO
LogAccess
(optional)

(YES/NO) Some CGI applications, such as CHAT room services, operate by causing web browsers to request page updates every few seconds. Logging this kind of activity fills access logs very quickly. This option allows high volume directory access to be ignored. Default is YES.

Example:
 LogAccess = NO
LogErrors
(optional)

(YES/NO) This option allows error logging to be turned off. This option is seldom used but is available if needed. Default is YES.

Example:
 LogErrors = NO
Log404
(optional)

(YES/NO) This option allows requests for non-existent pages to be ignored and not logged. Web site hacker programs can produce many "404 Object not found" errors in you default directory. The volume this kind of error message can be so high that it is difficult to notice other kinds of errors, potentially masking service configuration problems. Default is YES.

Example:
 Log404 = NO

Configuring Security

 

One of the prime reasons for developing Bosco was to defend a web site from hacker attacks. Bosco achieves most of its robustness by remaining simple internally. Servers like Apache and Microsoft's IIS support so many features that it is difficult for their developers to avoid all possible security leaks. Many of the challenges faced by those developers simply do not exist in Bosco.

There are also adjustable security features in Bosco. You may enable or disable access to subdirectories in directories you define. You may enable or disable returning a listing of a directory's contents in response to requests.

Bosco also allows you to limit access to directories based upon User ID, Password checks. Each directory may have its own private user list. User lists may be shared between two or more directories. (A directory may have only one list, however.) The user lists consist of simple ASCII text files with comma separated user ID, password pairs on each line. These files are kept in human readable text form. They are not encrypted so are easy to edit and maintain.

Using unencrypted security files may seem at first like a security problem. The fact, though, is that if a hacker can get hold of an encrypted security file from a web server, he can usually decode one or more of the entries in a very short period of time. Only very complex (and slow running) encryption schemes would thwart this kind of attack. Bosco takes a different tack.

Bosco leaves its security files unencrypted but makes it easy to keep hackers from ever having access to these files. Bosco's internal coding is specifically built to avoid allowing access to the contents of directories not explicitly enabled in the "bosco.conf" configuration file. Unless you specifically define the Bosco "sec" directory for access or give subdirectory access permission to a directory that includes "sec" as a subdirectory, hackers will not be able get to these files.

AllowSubdirectories
(optional)

(YES/NO) This option allows you to tell Bosco to not allow accessing files in subdirectories to the one being defined. For system and file security, this option should be enabled whenever practical. Access to subdirectories would still be available by simply defining additional Bosco directory entries for each subdirectory. See the directory definition section above for further details. Default is NO.

Example:
 AllowSubdirectories = YES
AllowDirList
(optional)

(YES/NO) This option allow a directory listing to be presented to users if no DefaultFile is supplied. Users will be able to click on filenames (and subdirectory names) to read them. This feature is only used in a limited number of situations but is handy when appropriate. It is, however, potentially dangerous since all files in the directory will be shown, including files you might not want web users to know about. Default is NO.

Example:

 AllowDirList = YES
BasicDomain
(optional)

This option turns on UserID/Password checking. To access files in a directory, the web browser user will be queried for a UserID and Password. Obviously, for this to work, you must supply a UserID/Password list that the user may be authorized from. This is done by creating files in the "sec" directory that contain UserID and Password entries. No default value is provided.

Example:

 BasicDomain = CorpUsers

The content of a Bosco security file is simply a series of ASCII text lines containing comma separated user ID and Password pairs.

Example of a fictitious security file named "CorpUser":

 gary, test
 larry, whatever
 bigbob, tabasco

This file defines three users (gary, larry, and bigbob) and provides their passwords.

Note: User ID's and Passwords checking is case sensitive.

LoginTimeout
(optional)

This option may be used with directories using BasciDomain access control. This option is used to override the automatic user ID, password supplied by web browsers once a site using Basic Authentication has been successfully accessed. A situation where this might be an issue would be accessing a secured directory using a shared or public PC.

This is number of minutes since the last access of the secured directory allowed before a Basic Authentication query is returned by Bosco to the browser. No default value is provided.

Example:

 LoginTimeout = 20

 Note: The user must avoid allowing the web browser to save user ID and password. This option is typically presented with a pop-up dialog box immediately after a Basic Authentication user ID and password query dialog box is filled out by the user. Always answer "NO" to ths query.


Configuring CGI operation

 

CGI or Common Gateway Interface is a way in extend the functionality of a web server. Bosco recognizes two kinds of CGI extensions. The first is an executable program, typically a compiled C language program. This kind of extension has the normal Microsoft executable file extension, ".exe". When requested, Bosco runs this kind of CGI extension directly.

The second kind of CGI recognized is what is typically called a "script" file. Script files are typically text files containing program code written in an interpreted language such as Perl or PHP. To handle this kind of CGI extension, you must supply the fully qualified path to an interpreter for that language in the "SetExtension" entry described below.

Bosco's CGI operations are fully buffered. That is, CGI input and output is passed via intermediate files. This blocks the path of the vast majority of web site break-ins. A CGI program cannot be exploited to provide a open connection between a hacker's computer and Bosco's computer.

Using intermediate files for handling CGI program input and output does not, however, assure service security. Both directly executable and script CGI extensions contain active program code that could, itself, perform operations that compromise service security.

If CGI extensions are to be used, they should be obtained from only professional and trustworthy sources. Amateur programmers often do not understand security issues adequately to recognize when they have create a security problem in their code.

AllowRead
(optional)

(YES/NO) This option allows you to turn off read access to files in a CGI directory if not needed. This minimizes the possibility of hackers retrieving CGI file operational data. Default is YES.

Example:

 AllowRead = NO
SetExtension
(optional)

(ext, path) This option defines a CGI extension handler. This will typically be the name of a script file interpreter for Perl or PHP. One of these option lines is needed for each script type handled. Extension definitions may be made on a directory-by-directory basis though it is usually easier to define them service wide.

Example:

 SetExtension = pl, C:\perl\bin\perl.exe

A SetExtension entry is not needed for ".exe" CGI extensions.

AllowExtension
(optional)

(ext, (YES/NO)) This option enables or disables script operation. This may be done on a global basis but is typically done on a directory-by-directory basis.

Example:

 AllowExtension = pl, YES

In the this example, if a request is received from a browser for a file that has a file extension if .pl, the Perl interpreter defined in this "bosco.conf" file will be run, passing the name of this CGI file to it.

An AllowExtension entry is also needed for ".exe" CGI extensions.

Example:
 AllowExtension = exe, YES
SingleThreadCGI
(optional)

(YES/NO) Bosco is a multithreaded server and can handle hundreds of simultaneous requests for files and scripts. Unfortunately, some CGI scripts use files in a way that causes them to fail if more than one copy of the script is running at a time. This option tells Bosco to run only one CGI at a time in a directory. Default is NO.

Example:

 SingleThreadCGI = YES
AllowCgiCmd
(optional)

(YES/NO) Some CGI scripts require parameters be passed to them via the command line. This is the server behavior most often exploited to break into systems. The trick that is used is to run a system command program like "cmd.exe" and feed it a command line that causes the server give system access to a hacking program. Bosco uses several tactics to minimize the success of an attack like this, one of which is to simply not pass command line parameters. This option allows you to override this protection if you have a legitimate CGI script that needs parameters passed to it on via the command line. Very few professional CGI scripts use command line parameters. Default is NO.

Example:

 AllowCgiCmd = YES

Configuring ISAPI Operation

 

ISAPI (Internet Server Application Programming Interface) is a Microsoft specific web server extension mechanism. CGI programs and scripts are executed each time a request for one arrives. Between requests, there is no connection between the web server and the CGI program or script. This kind of operation is typically adequate for most business web applications.

ISAPI service extensions, on the other hand, directly connect into the internal code of the server. This is accomplished by use of Microsoft operating system Dynamic Link Library (DLL) mechanism. ISAPI extensions are connected to they web server via an operating system LoadLibrary system call. Incoming requests are passed to the ISAPI extension using direct subroutine calls.

In general, overall performance and usage by web browsers are equivalent when comparing CGI and ISAPI server extensions. ISAPI does, however, allow for somewhat more complex extensions to be built. This is primarily because ISAPI extensions are not unloaded between web requests.

ISAPI service extensions are not nearly as safe to use as CGI extensions. An ISAPI extension is running as if it was an integral part of the server's program code. A programming error in an ISAPI extension can easily crash the entire server. A program crash in a CGI will have no effect the server other than to cause it to return an error message to the browser that made the request. USE ISAPI EXTENSION WITH EXTREME CAUTION!

Configuring ISAPI operation is essentially the same as configuring CGI operation. Bosco does not allow ad-hoc ISAPI operation. All ISAPI extension used by Bosco must be explicitly defined in "bosco.conf". They are defined using an "SetExtension" entry.

Bosco will attempt to load the specified extension when it starts up. If the ISAPI DLL specified does not exist or it does not respond to ISAPI specific requests, startup will be aborted. Bosco keeps its ISAPI DLL extensions loaded until it shuts down.

The ISAPI configuration entries shown below are really just a repeat of those shown for CGI extensions above. They are shown here for constancy.

AllowRead
(optional)

(YES/NO) This option allows you to turn of read access to files in a ISAPI directory if not needed. This minimizes the possibility of hackers retrieving ISAPI file operational data. Default is YES.

Example:

 AllowRead = NO
SetExtension
(optional)

(ext, path) This option defines a CGI or ISAPI web server extension handler. This will typically be the name of a script file interpreter ISAPI DLL. One of these option lines is needed for each script type handled. Extension definitions may be made on a directory-by-directory basis though it is usually easier to define service wide.

Example:

 SetExtension = pl, C:\perl\bin\perl.dll
AllowExtension
(optional)

(ext, (YES/NO)) This option enables or disables script operation. This may be done on a global basis but is typically done on a directory-by-directory basis.

Example:

 AllowExtension = pl, YES

Some Final Notes

 

Keep in mind that Bosco is intended to be a reliable web server that is a simple to install and simple to manage. It is not intended to provide all of the functionality needed for very large and complex web server installations. Bosco should only be considered for use in installations where only a few thousand files will be served and no more than a few hundred users are expected to be using it at any given instant. Four small to medium sized businesses, Bosco should be more than adequate.

One of the more important things to do while configuring a Bosco installation is to keep it simple. Don't create any more virtual directories than you actually need. It is not necessary to create a complex configuration to start with. Simply add whatever new directories or other feature you need, when you actually need it. Stop and restart Bosco to make those changes take effect. Bosco's configuration entries are so simple that it is quite easy to avoid making changes that damage previously existing functionality.

Finally, I make no apology for limiting the functionality of Bosco. I saw no reason to create a competitor to Apache. That is a very competent server and it is free. It is, however, not simple to install or configure. There are books written and sold to teach people what to edit in the Apache configuration file to get it to do what they want. Instead, I chose to create something that is solid, reliable, simple to configure, and simple to use.

Enjoy