Installation and administration guide : Windows
Wiki ▸ Installation and Administration Guide : Windows
-
Installing with the Windows Installer
2.1. Configuring IIS
2.2. Configuring Apache
2.3. Oracle Support
-
3.1. Troubleshooting
1. Requirements
Before installing "Biferno for Windows" on your computer, be sure to have, at least, the following configuration:
-
Windows Operating System: as of today Biferno has been tested only on Windows 2000, 2003, XP but it should run also on other versions. Biferno doesn't run on Windows 95-98 or ME.
-
Free space on Hard Disk >= 10MB.
-
Free RAM >= 24MB (this requirement depends on the maximum number of users for your web site).
-
One of the following Web servers:
-
Microsoft's IIS (Internet Information Service) or an ISAPI compatible web server
-
Apache for Windows. Only the Apache2 module is distributed as a binary. If you have a previous version of Apache (1.x.x) you should recompile the module with the includes and libraries files of that Apache version (see Section 5, “Compiling and Installing from Sources”). Besides, if you want to use Apache 2 as web server, note that Biferno requires at least version 2.0.41 of it.
Download the Biferno Windows installer (file biferno-[version]-windows.exe) from the net or copy it from another distribution media (CD-ROM) into a working directory. Now start the installer by double-clicking on the installer icon.
Warning
If Microsoft's IIS is running on the machine where Biferno is being installed, you will need to stop it before proceeding with the Biferno installation. Failure to do so will cause the installation to fail, because of a file lock set by IIS on the
BifernoISAPI.dlllibrary. The installer will not be able to replace theBifernoISAPI.dlllibrary if the library is present on disk (from a previous installation of Biferno) and is being used by IIS.
The installer installs the Biferno binaries and related files, creates the Biferno service as a Windows service and starts it. When the automatic installation procedure is completed, you will have to complete the installation manually by configuring your web server (either Microsoft's IIS or Apache) to use the appropriate Biferno module.
2.1. Configuring IIS
To configure IIS to use Biferno, open the "Computer Management" control (in Control Panel/Administration Tools) and right click on the "Services and Applications->Internet Information Services->Default Web Site" property. Choose the "Properties" item. Notice that we assume that the IIS software has been installed before installing Biferno.
Figure 3.1. IIS: Default Web Site Property
The "Properties" window will appear. Select the "Home Directory" tab:
Figure 3.2. IIS: Home Directory Panel
Now press the "Configuration" button, and in the "Application Configuration" window click on the "Add" button.
Figure 3.3. IIS: Application Configuration Panel
A configuration window will appear, where you will enter the following information:
Enter in the "Executable" column the path to the BifernoISAPI.dll dynamic library that has been installed by the Biferno installer in your inetsrv directory of the System32 directory. In Windows NT/2000/XP, this is the system32\inetsrv folder within the Windows folder where your Windows operating system has been installed.
Enter in the "Extension" column the .bfr suffix.
The information you entered will look similar to the following:
Figure 3.4. IIS: Add/Edit Application Extension Mapping
At this point restart the web service using "IIS Admin Service". You must restart also the "Internet Information Services" right clicking on the "Services and Applications->Internet Information Services->Default Web Site" property in "Computer Management" control and choosing start.
The configuration procedure for IIS is finished.
2.2. Configuring Apache
Copy the mod_biferno.so Apache module from the installation directory (by default: Program Files/Biferno/ApacheModule) into the Apache modules directory (by default: Apache Group/Apache2/modules).
Append the following lines to the Apache configuration file (by default: Apache Group/Apache2/conf/httpd.conf):
LoadModule biferno_module modules/mod_biferno.so
AddHandler biferno-handler .bfr Note
If you are using a version of Apache prior to 2.x the configuration could be slighty different (the obsolete AddModule directive can be needed):
LoadModule biferno_module modules/mod_biferno.so
AddHandler biferno-handler .bfr
AddModule mod_biferno.c If you wish to specify the index.bfr as the default script, modify the DirectoryIndex directive in your Apache configuration file. The line containing the DirectoryIndex directive will be similar to the following:
DirectoryIndex index.html [some_other_index_names] and it should be modified to read:
DirectoryIndex index.html [some_other_index_names] index.bfrThe configuration procedure for Apache is finished.
2.3. Oracle Support
If you want to use the Oracle support that Biferno provides, you must manually copy the oracle_bfr.dll from the Program Files\Biferno\BifernoHome\InactiveExtensions directory to the Program Files\Biferno\BifernoHome\Extensions directory and restart the Biferno service.
To verify the installation move the test.bfr file (from the BifernoHome directory) in the Web Server Document Root folder. From your browser invoke the URL:
http://[www.yourserver.com]/test.bfr
If the installation has been performed correctly the browser will show the following output:
Ok, Biferno was correctly installed
3.1. Troubleshooting
-
The request of page test.bfr fails:
-
check if the web server (IIS or Apache) is started. In particular, make request of a .html page. If the page is served, than skip this step, otherwise check the error log file of Apache (
[Program Files]\Apache Group\Apache2/logs) or the System Event Log for IIS. -
if the server is up (see previous step), be sure that the Biferno service (or the Biferno.exe application) is up and running. If you suspect problems on Biferno startup, it can be useful to debug it using the Biferno.exe application (instead of the service).
-
for IIS users: if you moved
BifernoISAPI.dllin other location than the default one, and the new path toBifernoISAPI.dllcontains white spaces or special characters, IIS has problem locating the dll. Avoid spaces inBifernoISAPI.dllpath name. -
The page test.bfr returns the following text:
You are not authorized to view this page
You do not have permission to view this directory or page using the credentials you supplied.
-
for IIS users: IIS (probably) has not sufficient privileges to load the BifernoISAPI dll. Check the Properties->Security panel of file BifernoISAPI.dll to solve the problem.
-
check also the Properties->Security panel of file test.bfr.
-
The page test.bfr returns the following text:
If you are seeing this, Biferno was not correctly installed.
Make sure the web server is correctly configured to handle .bfr files (See "Biferno installation guide" for instructions).
* in this case the web server is responding to requests but doesn't invoke the BifernoISAPI.dll (IIS) or the mod_biferno.so (Apache) for ".bfr" requests. Check the configuration explained in Section 2.1, “Configuring IIS” or Section 2.2, “Configuring Apache” to solve this problem.
## 4. <a name="WinUpdating">Updating from a Previous Version</a>
To update from a previous version, it is safe to use the file "biferno-[version]-windows.exe".
**Warning**
>If Microsoft's IIS is running on the machine where Biferno is being installed, you will need to stop it before proceeding with the Biferno installation. Failure to do so will cause the installation to fail, because of a file lock set by IIS on the BifernoISAPI.dll library. The installer will not be able to replace the BifernoISAPI.dll library if the library is present on disk (from a previous installation of Biferno) and is being used by IIS.
If the version of Biferno you want to install is already installed, the installer will prompt you using a dialog with a button that allows remove the current installation before performing a new installation from scratch. Click the "Remove" button and then re-execute a clean installation (note that for the Windows installer "beta" version are considered equal, for example 1.0b4 is the same as 1.0b5).
Some users reported:
After removing the current installation and retry a new clean installation the Installer occasionally fails with a "No permission to install service" error. Restarting the computer after remove should fix this problem.
**Warning**
>The bifernoadmin, Utils and Man folders are completely replaced when an installation is updated. Therefore it is not safe to use any of these folders to store your own files.
On the contrary, in the Extensions folder only files in the Biferno distribution are replaced leaving untouched all files created by the user. It is perfectly OK to use the Extensions folder to store your own extensions.
If you are using the Oracle support that Biferno provides, you must manually update it. To do the update, copy the oracle_bfr.dll from the [path to Program Files]\Biferno\BifernoHome\InactiveExtensions directory to the [path to Program Files]\Biferno\BifernoHome\Extensions directory and restart the Biferno Service.
## 5. <a name="WinCompiling">Compiling and Installing from Sources</a>
To install Biferno from sources you will need the VisualC++ compiler, version 6 or later (msdn.microsoft.com).
Environment variables BFR_APACHEDIR and BFR_ORACLEDIR have been added from version 1.0.2 of Biferno in order to specify the path for Apache module and Oracle extension libraries (examples: BFR_APACHEDIR=C:\Program Files\Apache Group\Apache2 and BFR_ORACLEDIR=C:\Oracle\ora81). You must define these variables if you want to compile the Apache module and/or the Oracle extension.
Download the file "biferno-[version]-windows.src.zip" from the net or copy it from another distribution media (CD-ROM) and unzip it. Then open the VisualC file:
Projects\VisualC\Biferno\Biferno.dsw
and build the project choosing the "Build->Rebuild All" menu item (this may take several minutes).
**Note**
>Before compiling, the following search includes path must be added to your VisualC environment (menu "Tools option->Directories"):
[path to Biferno Sources]\XLIB\XLIB\C_INCLUDE
[path to Biferno Sources]\XLIB\XLIB\C_INCLUDE\MD5 (this is needed from Biferno version 1.1)
[path to Biferno Sources]\XLIB\XLIBWIN\C_INCLUDE
[path to Biferno Sources]\SOURCE\CLASSES\C_INCLUDE
[path to Biferno Sources]\SOURCE\SOURCES\C_INCLUDE
[path to Biferno Sources]\XLIB\XLIBHTTP\C_INCLUDE
[path to Biferno Sources]\PROJECTS\RESOURCES
To compile, respectively, the apache, oracle, mysql modules:
[path to program files]\APACHE GROUP\APACHE2\INCLUDE
[path to oracle home]\ORA81\OCI\INCLUDE
[path to program files]\MYSQL\INCLUDE
After the build process is finished the compiled binaries can be found in:
Distribution\Biferno_Win
**Warning**
>The following binaries: mod_biferno.so (Apache module), mysql_bfr.dll and oracle_bfr.dll are not compiled by default because, generally, they need third-party includes and libraries not available to all developers. To build them, modify the dependencies of the "Build" project (from the menu "Project->Dependencies") before building, or open directly the single projects: Projects\VisualC\BifernoApache\BifernoApache.dsp, External\mysql\mysqlVC\mysqlVC.dsp and External\oracle\oracleVC\oracleVC.dsp).
To install the version of Biferno just compiled follow these steps:
Create BifernoHome: create a folder named Biferno in your "Program Files" folder and move the folder Distribution\Biferno_Win\BifernoHome inside it.
Set the BifernoHome registry value: open the regedit application and add the following key to the Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Tabasoft\Biferno\BifernoHome as a string with value: [path to Program Files]\Biferno\BifernoHome (substitute [path to Program Files] with the real name of the "Program Files" folder on your system, e.g. C:\Program Files\Biferno\BifernoHome)
Configure the web server:
IIS: copy the file Distribution\Biferno_Win\ISAPIModule\BifernoISAPI to the your "inetsrv" directory of System32 directory. In Windows NT/2000/XP, this is the system32\inetsrv folder within the Windows folder where your Windows operating system has been installed. Then configure the module as explained in Section 2.1, “Configuring IIS”
Apache: Configure the module as explained in Section 2.2, “Configuring Apache” (the module, after compilation, is in Distribution\Biferno_Win\ApacheModule)
Add the service registry: if you want to use Biferno as a service you must add the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\bifernosvc to the registry (see Section 8, “Biferno on Windows: Advanced Concepts”). To do so double click the file BifernoSvc.reg. A bifernosvc key will be added in: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ open the key (with regedit) and fill the value of ImagePath with: [path to Program Files]\Biferno\BifernoHome\bifernosvc.exe (substitute [path to Program Files] with the real name of the "Program Files" folder on your system). See, as an example, the figure Figure 3.7, “Biferno Windows Service Registry”
Start IIS and BifernoService
Copy the folders bifernoadmin, Utils and Man into [path to Program Files]\Biferno\BifernoHome
## 6. <a name="WinUninstalling">Uninstalling</a>
To uninstall Biferno follow these steps:
If you are using IIS stop the "IISAdmin" service.
Double-click the biferno-[version]-windows.exe installer file and choose the Remove button.
If you are using IIS, delete the IIS configuration as explained in Section 2.1, “Configuring IIS”
If you are using Apache, delete the Apache configuration as explained in Section 2.2, “Configuring Apache”, and remove the mod_biferno.so module from the Apache directory (by default: Apache Group/Apache2/modules)
## 7. <a name="WinBifernoCtl">Administration (BifernoCtl: Flush, Reload, Start and Stop)</a>
The Bifernoctl application, which is launched via the Biferno program group in the Windows "Start" menu, allows to control the Biferno server. The application allows to start and stop the Biferno server in console or service mode, to reload Biferno and to flush the Biferno cache.
**Figure 3.5. BifernoCtl: Start and Stop**
[[/images/instguide/bifernoctl2.gif]]
**Figure 3.6. BifernoCtl: Flush and Reload**
[[/images/instguide/bifernoctl1.gif]]
More information on reloading Biferno and flushing the cache can be found in the "Biferno: Language Guide" document.
## 8. <a name="WinAdvanced">Biferno on Windows: Advanced Concepts</a>
This paragraph explains the details of Biferno operations on the Win32 operating system.
On the Windows operating system, Biferno is implemented as a web server plugin (called BifernoISAPI.dll for IIS, mod_biferno.so for Apache). The plugin communicates (via TCP/IP sockets) with a local multithreaded server application (called Biferno.exe or bifernosvc.exe). The plugin intercepts requests of pages ending in ".bfr" to the web server (using ISAPI or AP callbacks), and passes the page requests to the Biferno application. The Biferno application responds to plugin requests and can run in interactive console mode (Biferno.exe) or as a system service (bifernosvc.exe).
The Web server must be informed by configuration of the existence and location of the Biferno plugin (see Section 2.1, “Configuring IIS” or Section 2.2, “Configuring Apache”).
Biferno uses a special folder (called BifernoHome) for all its configuration settings. On Windows this location of this folder is choosen at installation time. The default is :
[path to Program Files]\Biferno\BifernoHome
This folder contains, among others, the folllowing folders and files:
bifernoadmin folder: contains all bifernoadmin source files. If this folder is not present, Biferno will work correctly, but bifernoadmin will not be accessible (the bifernoadmin application is described in the "Biferno: bifernoadmin Guide" document).
Utils folder: contains a set of Biferno utilities for script development. The presence of this folder is not mandatory for Biferno to be fully functional.
Man folder: contains the man pages in xml format as displayed in the Biferno Reference On Line (see "Biferno: bifernoadmin Guide"). If this folder is not present Biferno will function correctly but the Reference on line will not have field descriptions.
Extensions folder: is the folder containing all the BAPI extensions (classes and functions written in the C language plug-ins). If this folder is not present Biferno creates it at the first run and will continue to operate normally, but no extensions will be loaded.
Biferno.exe file: is the executable of the Biferno Console application
bifernosvc.exe file: is the executable of the Biferno Service application
BifernoCtl.exe file: the application BifernoCtl (see Section 7, “Administration (BifernoCtl: Flush, Reload, Start and Stop)”).
In addition to the above, the following files are automatically created by Biferno in BifernoHome folder at the first run:
biferno.conf: is the file for the Biferno advanced performance settings (see the Appendix in "Biferno: Language Guide").
Biferno.config.bfr: the config file for the main application (see the chapter on applications in "Biferno: Language Guide").
Biferno.pid: contains the process id of the Biferno application currently running (Console or Service).
bifernoctl.log: the log file of BifernoCtl.
BifernoServer.log: the log file of Biferno Console.
BifernoServer.log_CANT_INIT_BIFERNO_TWICE: this file is created if there has been an attempt to start Biferno Console twice.
BifernoService.log: the log file of Biferno Service.
BifernoService.log_CANT_INIT_BIFERNO_TWICE: this file is created if there has been an attempt to start Biferno Service twice.
BifernoSmtp.doing: ths file is for Biferno internal use (is used to syncronize the Biferno SMTP (Simple Mail Transfer Protocol) asyncronous background thread).
BifernoSmtp.log: the log file for the Biferno SMTP (Simple Mail Transfer Protocol) threads.
BifernoSmtp.que and BifernoSmtp.que.temp: are files used by Biferno for the Biferno SMTP (Simple Mail Transfer protocol) asyncronous background thread.
Persistent folder: used for persistent variables storage (text and binary file), see the chapter on applications in "Biferno: Language Guide".
None of the above files is modified when an update process is executed.
Biferno uses the Windows registry database to store information about the current environment. Biferno registries can be found under the key:
HKEY_LOCAL_MACHINE\SOFTWARE\Tabasoft\Biferno
In particular the following registry are used:
BifernoHome: contains the path of BifernoHome folder, default is [path to Program Files]\Biferno\BifernoHome. Don't modify this value. If you want to move the BifernoHome to a different location, uninstall Biferno and reinstall it in the new location.
ExeMode: contains a string indicating the mode Biferno is running in. Possible values are SERVICE or CONSOLE. This value is set internally by Biferno, don't modify it manually.
ConsolePath: is the path of the biferno console executable file, default is [path to Program Files]\Biferno\BifernoHome\Biferno.exe. This value is set internally by Biferno, don't modify it manually.
ServicePath: is the path of the biferno service executable file, default is [path to Program Files]\Biferno\BifernoHome\bifernosvc.exe. This value is set internally by Biferno, don't modify it manually.
Port: contains the number of the TCP/IP port used for the communication between the web module and the Biferno (service or console), default is 4999. Users can modify this value (restart Biferno and the Web Server after modification).
CtlPort: unused.
The biferno service registry can be found under the key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\bifernosvc
and looks as in the following picture:
**Figure 3.7. Biferno Windows Service Registry**
[[/images/instguide/winservice.gif]]
The service can be managed (as usual for Windows users) from the "Services" control panel inside "Settings\Control Panel\Administrative Tools\"