Copyright © 2003 Tabasoft S.a.s.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled Appendix 2, GNU Free Documentation License.
Table of Contents
List of Figures
Table of Contents
There are three methods to install Biferno under Linux:
Use the fully automated installation and configuration procedure based on the rpm package.
Perform a manual installation from the Biferno binaries tar archive.
Compile and install from the Biferno source code tar archive.
We strongly recommend the package-based installation, described in Section 2, “Installing from the RPM Distribution”. Instructions for installing from the binaries tar archive and from the source code tar archive are provided in Section 3, “Installing from the Binary tar Archive” and Section 4, “Compiling and Installing from Sources”, respectively.
Before installing Biferno for Linux on your computer, be sure to have, at least, the following configuration:
Linux operating system: as of today Biferno has been tested only on Linux RedHat 6.2, 7.3, 8.0 and 9.0, but it has been reported to successfully compile and run on other Linux distributions as well.
Free space on Hard Disk >= 10MB.
Free RAM >= 24MB (this requirement depends on the maximum number of users for your web site).
The Apache Web server (version 1.x or 2.x). If you want to use Apache 2 as web server, note that Biferno requires at least version 2.0.41 of it.
The Biferno distribution in RPM form consists of a main biferno package and
of optional web server modules and database support packages. You should
always install the main package, and will need to install only the web server
module and database support package for the web server and database you are
planning to use, if any. For a typical configuration consisting of Biferno
in combination with an Apache 1.x web server and an Oracle database, you
should e.g. install the biferno-[vers].i386.rpm, biferno-apachemodule-[vers].i386.rpm, and biferno-oraclesupport-[vers].i386.rpm packages.
In the future other extensions will be added to Biferno download for Linux.
Download the main Biferno rpm package from the net or copy it from another
distribution media (CD-ROM) into a working directory. Biferno rpm package
files are named according to the scheme
biferno-.
The filename for the rpm package for Biferno version 1.4.0, rpm
release tag 1, would be [biferno_version]-rpm_release_tag.i386.rpmbiferno-[vers].i386.rpm. We assume in the following
that the Biferno rpm file is called biferno-[vers].i386.rpm.
The installing user needs to have root privileges. After changing directory to the working directory, digit the following commands:
$rpm -ivbiferno-[vers].i386.rpm
This will install the software and configure the environment. The installation procedure is fully automatic and will go through the following steps:
Biferno binaries are copied to /usr/bin.
The Biferno home directory is copied to /home/BifernoHome.
A user and a group called “biferno” are created.
Biferno configuration information is added to the Apache configuration file. This information will be automatically removed when the package is uninstalled.
Biferno is installed as a system service (using the
chkconfig utility) and its initialization script
biferno is copied to the
/etc/init.d directory. By default, Biferno will
be started automatically when the system is booted in run levels 3, 4
and 5.
Assuming you need the biferno-apachemodule-[vers].i386.rpm, and biferno-oraclesupport-[vers].i386.rpm packages for your
configuration, change directory to the working directory where you have
downloaded the files and digit the following commands (the installing user
needs to have root privileges):
$rpm -ivbiferno-apachemodule-[vers].i386.rpm$rpm -ivbiferno-oraclesupport-[vers].i386.rpm
Biferno can be removed from the system using the rpm command as follows:
$rpm -evbiferno-[vers].i386.rpm
This will also remove all configuration added by the automatic installation procedure from the system.
![]() | Note |
|---|---|
Before removing the biferno rpm package, remove all the biferno extensions and modules installed, otherwise the rpm will complain about dependancies between packages |
A Biferno rpm package can be upgraded using the rpm -U
new-biferno-rpm-package command. After the upgrade
more steps are needed depending on "what" has been upgraded:
if biferno has been upgraded restart it with command bifernoctl restart
if the apache module has been upgraded a command apachectl restart is needed
if a biferno extension (database support or other) has been upgraded a command bifernoctl reload is needed (note that bifernoctl restart comprises bifernoctl reload)
When performing an upgrade using rpm -U, files that
were part of the previous Biferno installation are removed before the new
version is installed. In general, it is not safe to store user files in biferno directorries (e.g.
BifernoHome/bifernoadmin, BifernoHome/Utils or
BifernoHome/Man), as they will be removed during an upgrade of
the software.
![]() | Expert Note: Manual Configuration with the rpm Package |
|---|---|
It is possible to use rpm only to install the
binaries and the
We advise to do this only if you are an experienced system administrator. |
![]() | RedHat 6.1 Installation Note |
|---|---|
An rpm installation problem has been reported on a RedHat 6.1 system that had been upgraded to rpm version 4, in which the rpm program complains about failed dependencies while all the needed library are indeed installed and the loader on the target machine is correctly configured to find them. For example, installing the oracle support: > rpm -i biferno-oraclesupport-1.0-4.i386.rpm error: failed dependencies: libclntsh.so.8.0 is needed by biferno-oraclesupport-1.0-4 Should you believe you are seeing this problem, try to use rpm -i --nodeps [rpm file] to tell rpm to skip the automatic dependency check. |
![]() | Warning |
|---|---|
You should use the manual installation procedures only if you are not able to use the rpm command and if you are an expert system administrator. |
Download the Biferno compressed tar file from the net or copy it
from another distribution media (CD-ROM) into a working directory. We
assume in the following that the rpm file is called biferno-[vers].i386.tar.gz. After
changing directory to the working directory, unpack the archive (notice
that the installing user needs to have root privileges):
$tar -zxvfbiferno-[vers].i386.tar.gz
Now enter the directory you have just created.
$ cd biferno-1.4.0/Linux/i386
Install binaries:
$cd bin$install -m 755 -o 0 -g 0 bifernod/usr/bin$install -m 755 -o 0 -g 0 bifernoctl/usr/bin$cd ../../..
Copy the biferno init script into the init.d directory:
$cd noarch/init$install -m 755 -o 0 -g 0 biferno /etc/init.d$cd ../../Linux/i386
Copy the BifernoHome directory to the target
location:
$cp -rBifernoHome//home
Install the Apache module. You need to decide which is the appropriate
module for your server (say your server is Apache 1.x with EAPI support,
then choose mod_biferno_eapi.so), copy it into the Apache
modules directory and finally create a link as follows:
$cd modules$install -m 755 -o 0 -g 0 apache/mod_biferno_eapi.so \ /etc/httpd/modules$(cd /etc/httpd/modules && ln -f -s mod_biferno_eapi.so \ mod_biferno.so)
Add the “biferno” group and user if they do not already exist:
$/usr/sbin/groupadd biferno$/usr/sbin/useradd -c "Biferno" -g biferno -s /bin/bash -r -d \/home/BifernoHomebiferno
Fix ownerships on /home/BifernoHome:
$chown -R biferno/home/BifernoHome$chgrp -R biferno/home/BifernoHome
Add biferno to the system startup profile:
$ /sbin/chkconfig --add biferno
Verify that your Apache binary has been compiled with the
--enable-module=so option enabled that supports the
use of external DSO (Dynamic Shared Object) modules. To check if this
is the case use the command:
$ httpd -l
and verify that the mod_so string appears in
the list printed on the screen.
Append the following lines to the Apache configuration file
(usually /etc/httpd/conf/httpd.conf):
LoadModule biferno_module modules/mod_biferno.so AddHandler biferno-handler .bfr
![]() | Note |
|---|---|
Some versions of Apache require a different configuration. If you have problem with the previous one, try with the following: LoadModule biferno_module modules/mod_biferno.so AddHandler biferno-handler .bfr AddModule mod_biferno.c
(the command |
If you wish to specify the index.bfr as
the default script, modify the DirectoryIndex directive
in your the 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.bfr
To work with bifernoadmin (see Manual) some versions of Apache require this directive:
<Directory /home/BifernoHome/bifernoadmin> Options None AllowOverride None Order deny,allow Allow from all </Directory>
At this point you should perform the post-installation steps described in Section 5, “Launching Biferno” to make biferno operational.
If necessary, stop bifernod with /sbin/service biferno stop. Then remove it from the system startup profile with /sbin/chkconfig --del biferno.
Remove the biferno user with /usr/sbin/userdel
biferno. This will remove the bifernod group as
well.
Remove the biferno init script from the
init.d directory with rm
/etc/init.d/biferno.
Remove the biferno home directory with rm -rf
/home/BifernoHome.
Remove the biferno configuration from the Apache
configuration file (lines between the <IfDefine
HAVE_BIFERNO> and </IfDefine>
tags).
Restart httpd to unload the bifernod module with /usr/sbin/apachectl restart.
Download the Biferno source archive, e.g. biferno-[vers].src.tar.gz, from the net or
copy it from another distribution media (CD-ROM) into a working
directory. Expand the archive.
![]() | Note |
|---|---|
The |
The main makefile (master makefile) is located in the
_Unix directory in the biferno-[vers] directory. From within
the _Unix directory you can issue the
make command to build Biferno and the make
install command to install it on your machine (root privileges are
needed for installation). The output of the make help
command documents additional options.
The default for the master makefile is not to build any Web server module or database support extension. This behavior can be changed by defining an appropriate variable to make on the command line (the output of the make help command documents the available variables).
This means that e.g. to compile Biferno along with, say, the Apache Web server module (version 2.x) and the MySQL (version 4.x) database support extension, one should issue the following command:
$ make APACHE2=1 MYSQL4=1
Similarly, to compile and install compile Biferno along with the above extensions, the command is:
$ make APACHE2=1 MYSQL4=1 install
The make install command will install Biferno
binaries, man pages, init scripts, and copy utilities and reference pages
directories to the /home/BifernoHome directory (the directory is automatically
created if necessary). To make Biferno fully operational, a couple of manual
configuration steps are necessary. These steps are the same as described in
Section 3.1, “Configuration” for the installation from a binary tar
archive.
Biferno is not started automatically after the installation is completed, because it is necessary to restart the Apache server before the installation can be fully operational. Restarting Apache should be done manually at a time suitable to the system administrator as it will disrupt operations on a live web server.
To make Biferno operational, you can either restart the machine, or perform the following steps:
Start the bifernod daemon and the bifernoctl monitoring process:
$ /sbin/service biferno start
Restart httpd:
$ /usr/sbin/apachectl restart
Environment variables which must be defined in the startup environment for the Biferno daemon, such as the variables PATH or LD_LIBRARY_PATH (used by the system to locate the dynamic libraries) must be defined in a file called bifernodefs.sh.
This file must be located in /etc/init.d, and its content, if the file exists on disk, is sourced from the biferno startup script (/etc/init.d/biferno).
For example, to add the /mylibraries directory to the default search path of dynamic libraries (LD_LIBRARY_PATH), one might create the file /etc/init.d/biferno/bifernodefs.sh (readable by the startup user, root) and write the following in it:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/mylibraries
You should not modify the startup script itself, as the modifications may be overwritten by the installation of future versions.
At this point, you should have completed the installation procedure and have restarted your web server. Now it is time to test the installation.
In order to do this, you will need to copy the test.bfr
file from the distribution (from the BifernoHome
directory) into the root directory of your web server. You should also make
sure that Biferno is running.
Finally, from your favorite browser, invoke the URL:
http://www.yourserver.com/test.bfr
If the installation has been performed correctly, the browser window will show the following output:
Ok, Biferno was correctly installed
This confirms that the test.bfr page you
requested was correctly interpreted by bifernod.
The request of page test.bfr fails:
- the web server (Apache) is not started. Check the error log file of
Apache to check the reason (usually in /var/log/httpd/error_log or /usr/local/apache2/logs/error_log).
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
mod_biferno.so for ".bfr" requests. Check the configuration of the httpd.conf file and, in particular the step 5 of Section 3.1, “Configuration”
The page test.bfr returns the following text:
ERROR: 2 (No such file or directory) Biferno is down (file /tmp/biferno.str not found)
or
ERROR: 61 (Connection refused)
- the demon bifernod is not started. The web server is running and invokes correctly the mod_biferno.so but the module can't reach the biferno demon and send it requests. To debug bifernod startup, start it in interactive mode using the command: bifernod -i.
bifernod -i immediately exits with message:
Exiting... Permission denied
- bifernod has not sufficient privileges to write in BifernoHome folder. Try with the command (as root): chown -R biferno.biferno /home/BifernoHome/
bifernod -i exits with message:
Exiting... Address already in use
- try to remove the pipe name file with command: rm /tmp/biferno.str
Biferno doesn't start at the computer startup.
- Some linux distributions (i.e. Trustix) require the startup script to be in /etc/init.d
(not in /etc/init.d). Move it and retry.
Biferno Apache module RPM installation fails with message:
httpd >= 2.0.41 is needed by biferno-apache2module
Check your version of Apache using the command httpd -v. Some users reported
this error message also with versions of Apache > 2.0.41. To bypass this error add the RPM
option --nodeps to the rpm command.
Administration under Linux (and MacOSX) is performed via the bifernoctl utility. The manual pages in Appendix 1, Unix Manual Pages document the use of the bifernoctl utility and of the bifernod program.
This paragraph explains the details of Biferno operations on Linux operating system.
On Linux operating system, Biferno is implemented as an Apache module called mod_biferno.so communicating (using Pipe Names) with a local multithreaded
daemon application (called bifernod). The module intercepts requests of pages
ending in ".bfr" to the web server, and
passes the page requests to the bifernod. bifernod
responds to module requests. bifernod can run also in interactive mode if invoked with the command: bifernod -i.
The Web server (Apache) must be informed by configuration of the existence and location of the mod_biferno.so module (see the "Apache configuration" item in Section 3.1, “Configuration”).
Biferno uses a special folder (called BifernoHome)
for all its configuration settings. On Linux the location of this folder is:
/home/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.
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").
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.
BifernoSmtp.doing: this 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.
biferno_pst.s.bfr and biferno_pst.x.bfr: files used for persistent variables storage (text and binary file), see the chapter on applicatons in "Biferno: Language Guide".
bifernoctl.pid: is process id number of the bifernoctl process when started as sentinel process (see Appendix 1, Unix Manual Pages).
mod_biferno.log: is the log of the apache module.
None of the above files is modified when an update process is executed.
Table of Contents
There are two methods to install Biferno under MacOSX:
Use the fully automated installation and configuration procedure based on the Apple installer Biferno package.
Compile and install from the Biferno source code tar archive.
We strongly recommend installing via the Apple Installer package as described in Section 2, “Installing with the Apple Installer Package”. The steps to install from the source code tar archive is described in Section 3, “Compiling and Installing from Sources”.
Before installing Biferno for MacOSX on your computer, be sure to have, at least, the following configuration:
System version 10.2 (Jaguar) or greater is required to correctly run Biferno on the MacOSX platform.
Free space on Hard Disk >= 10MB.
Free RAM >= 24MB (this requirement depends on the maximum number of users for your web site).
The Apache Web server (version 1.x or 2.x). If you want to use Apache 2 as web server, note that Biferno requires at least version 2.0.41 of it.
Verify that your Apache binary has been compiled with the
--enable-module=so option enabled that supports the
use of external DSO (Dynamic Shared Object) modules. To check if this
is the case use the command:
$ httpd -l
and verify that the mod_so string appears in
the list printed on the screen.
Download the installer package, e.g.
biferno-,
(where 1.4.0-osx.dmg1.4.0 should be replaced by the
version of the downloaded software) from the net or copy it from another
distribution media (CD-ROM). Double-click on the .dmg file icon to
mount the disk image on your
desktop.
A disk icon named
biferno- is
now on your desktop. Double-click this icon to open a window showing the
package file and double click the package file to start installation
(recent versions of Safari should handle all these actions for you).
1.4.0-osx
After supplying your password to the installer, accepting the license agreement and choosing the destination disk, the automated installation procedure will install and configure Biferno for operation on your machine. The procedure is fully automatic and will go through the following steps:
Biferno binaries are copied to /usr/bin.
The Biferno home directory is copied to /Users/BifernoHome.
A user and a group called biferno are created.
Biferno configuration information is added to the Apache configuration file. This information will be automatically removed when the package is uninstalled.
The Biferno initialization folder (called
Biferno) is copied to the
/Library/StartupItems directory to automatically
start Biferno when the system is booted.
Some other collateral tasks as the installation of the Biferno Control Panel in the "System Preference" application
At the end of the installation process you are asked to restart the computer. You can avoid this if you restart Apache and start Biferno manually. Apache can be restarted in "System Preference -> Sharing -> Web sharing" and Biferno can be started from System Preference -> Biferno".
The installer needs to know the version of apache installed on your computer
in order to choose the correct biferno-apache module to install.
It obtain the version of apache using the command:
httpd -v. The module is then copied in the folder whose
location is in the output of command: apxs -q LIBEXECDIR.
Then the installer adds the biferno LoadModule and
AddHandler directive
to the httpd config file found in the field "SERVER_CONFIG_FILE" of the output
of command: httpd -V.
To compile Biferno you need to install the Developer package from Apple (see http://developer.apple.com).
![]() | Warning |
|---|---|
You should compile and install from sources only if you are not able to use the Apple installer package and if you know your way under MacOSX. |
Download the Biferno source archive, e.g. biferno-[vers]-osx.src.tgz from the net or
copy it from another distribution media (CD-ROM) into
a working directory. Expand the archive.
The XCode projects are in the folder "Projects". Open the projects and build them following these steps.
Open the project, set "BuildAll" as active target and build the project.
This step builds the executables bifernod and bifernoctl)
apachemodule: Open the project and build it. This step builds the module of biferno for Apache.
Depending on the version of Apache you are using you may want to change the setting of the directory containing the apache includes (Edit Project Setting, tab Build, Setting "User Header Search Path"). Current include path is "$(SDKROOT)/usr/include/httpd"
An alternative to XCode to compile the apache module is the "apxs" terminal command.
Open a terminal window, cd to the folder Projects/ApxsModule then type "make".
The command builds the biferno apache module using the tool apxs in canonical location. To use a different apxs file type:
make APXS=[path to apxs]
For example if you have installed a version of apache 2.2 in the folder /usr/local/apache22 and want a module for that version of apache type:
make APXS=/usr/local/apache22/bin/apxs
The projects listed here are recommended but not mandatory for a correct functioning of Biferno.
externals (target BuildAll): set "BuildAll" as active target and build project (builds some useful extensions)
BifernoPanel: builds the preference pane to administer Biferno
additional:
this project contains some targets to build additional extensions of Biferno
- mysql:
builds the extension "mysql_bfr.so" to call MySQL from Biferno. You must have mysql installed on your machine.
The target "mysql" searches the mysql include headers in: "/usr/include/mysql" or "/usr/local/mysql/include". If you have the MySQL include headers in some other location, in XCode set the active target to "mysql", then change the value of: Edit Active Target "mysql" -> Build -> "User Header Search Path"
- postgres:
builds the extension "postgres_bfr.so" to call PostgreSQL from Biferno. You must have PostgreSQL installed on your machine.
The target "postgres" searches the postgres include headers in: "/usr/include/pgsql" or "/usr/local/pgsql/include". If you have the PostgreSQL include headers in some other location, in XCode set the active target to "postgres", then change the value of: Edit Active Target "postgres" -> Build -> "User Header Search Paths"
The target "postgres" searches for libraries in path: "/usr/local/pgsql/lib". If you have the PostgreSQL libraries in some other location, in XCode set the active target to "postgres", then change the value of: Edit Active Target "postgres" -> Build -> "Library Search Paths"
- pop3:
builds the extension "pop3_bfr.so" that implements the POP protocol (Post Office Protocol) in Biferno. The extension needs the libspopc files (http://brouits.free.fr/libspopc/).
The target "pop3" searches the libspopc include header "libspopc.h" in: "/usr/include". If you have the libspopc include header in some other location, in XCode set the active target to "pop3", then change the value of: Edit Active Target "postgres" -> Build -> "User Header Search Paths"
The target "pop3" needs also the libspopc source files: format.c objects.c parsing.c queries.c session.c get them from the libspopc site (above) and put it in a folder called "libspopcsrc" in the root of biferno-[vers]-osx.src.
To install biferno after the compilation cd to folder biferno-[version]-osx.src and type:
sudo ./install.sh
![]() | Root Privileges on MacOSX |
|---|---|
To perform the above steps you will need root privileges. If the root user is not active on your machine, it can be activated by using the sudo passwd root command. You will be asked to supply a new password for the root user. Keep this password secret and remember that the root user can execute any administrative operation on your system. For more details on the activation of the user root on MacOSX look here. |
Biferno is not started automatically after the installation is completed, because it is necessary to restart the Apache server before the installation can be fully operational. Restarting Apache should be done manually at a time suitable to the system administrator as it will disrupt operations on a live web server.
To make Biferno operational, you can either restart the machine, or perform the following steps:
Start the bifernod daemon and the bifernoctl monitoring process in the System Preference Biferno Panel or typing:
$sudo /usr/bin/bifernod$sudo /usr/bin/bifernoctl -s
Restart the httpd daemon in the Web Sharing Preference Panel or typing:
$ sudo /usr/sbin/apachectl restart
Environment variables which must be defined in the startup environment for the Biferno daemon, such as the variables PATH or LD_LIBRARY_PATH (used by the system to locate the dynamic libraries) must be defined in a file called bifernodefs.sh.
This file must be located in /Library/StartupItems/Biferno, and its content, if the file exists on disk, are sourced from the biferno startup script (/Library/StartupItems/Biferno/Biferno).
For example, to add the /mylibraries directory to the default search path of dynamic libraries (LD_LIBRARY_PATH), one might create the file /Library/StartupItems/Biferno/bifernodefs.sh (readable by the startup user, root) and write the following in it:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/mylibraries
You should not modify the startup script itself, as the modifications may be overwritten by the installation of future versions.
At this point, you should have completed the installation procedure and have restarted your web server. Now it is time to test the installation.
In order to do this, you will need to copy the test.bfr
file from the distribution (from the BifernoHome
directory) into the root directory of your web server. You should also make
sure that Biferno is running.
Finally, from your favorite browser, invoke the URL:
http://www.yourserver.com/test.bfr
If the installation has been performed correctly, the browser window will show the following output:
Ok, Biferno was correctly installed
This confirms that the test.bfr page you
requested was correctly interpreted by bifernod.
The request of page test.bfr fails:
- the web server (Apache) is not started. Check the error log file of
Apache to check the reason (usually in /private/var/log/httpd/error_log).
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.
In this case the web server is responding to requests but doesn't invoke the
mod_biferno.so for ".bfr" requests.
Check the configuration of the httpd.conf file.
The page test.bfr returns the following text:
ERROR: 2 (No such file or directory) Biferno is down (file /tmp/biferno.str not found)
or
ERROR: 61 (Connection refused)
- the demon bifernod is not started. The web server is running and invokes correctly the mod_biferno.so but the module can't reach the biferno demon and send it requests. To debug bifernod startup, start it in interactive mode using the command: bifernod -i.
bifernod -i immediately exits with message:
Exiting... Permission denied
- bifernod has not sufficient privileges to write in BifernoHome folder. Try with the command (as root): chown -R biferno.biferno /home/BifernoHome/
bifernod -i exits with message:
Exiting... Address already in use
- try to remove the pipe name file with command: rm /tmp/biferno.str
Although you have installed mysql on your machine, the load of "mysql_bfr.so" extension fails with message:
Can't Initialize mysql client lib: NSObjectFileImageInappropriateFile (while looking for: libmysqlclient.dylib)
The installer of MySQL on MacOSX does not contain the library "libmysqlclient.dylib". Nevertheless you need it in order to use MySQL with Biferno on MacOSX.
The following note explain how to build and install it:
download the source of MySQL: the source package can be found in the section "Source downloads" of the mysql download page (remember to choose the same version ([version]) of mysql you have installed on your machine)
decompress the file in a folder (i.e. /Users/John/Documents)
type the following commands:
$cd /Users/John/Documents/mysql-[version]$./configure --enable-shared$make
When the make command has completed you will find the lib in the folder:
/Users/John/Documents/mysql-[version]/libmysql/.libs/libmysqlclient.dylib.
To complete the operation copy it to the default lib folder (as root):
$cd /Users/John/Documents/mysql-[version]/libmysql$sudo cp .libs/libmysqlclient.dylib /usr/lib
After this operation Biferno should load the library and initialize the mysql extension correctly.
To work with bifernoadmin (see Manual) some versions of Apache require this directive:
<Directory /home/BifernoHome/bifernoadmin> Options None AllowOverride None Order deny,allow Allow from all </Directory>
To uninstall biferno on MacOSX download the source package and run the script "uninstall.sh":
$cd [folder containing sources]$sudo ./uninstall
Administration under MacOSX is performed via the Biferno System Preference Control Panel. Additionally, as in Linux, the bifernoctl and the bifernod commands can be used. They are described in Appendix 1, Unix Manual Pages.
This paragraph explains the details of Biferno operations on MacOSX operating system.
On the MacOSX operating system, Biferno is implemented as an Apache module (called mod_biferno.so) communicating (using Pipe Names) with a local multithreaded
daemon application (called bifernod). The module intercepts requests of pages
ending in ".bfr" to the web server, and
passes the page requests to the bifernod. bifernod
responds to module requests. bifernod can run also in interactive mode if invoked with the command: bifernod -i.
The Web server (Apache) must be informed by configuration of the existence and location of the mod_biferno.so module.
Biferno uses a special folder (called BifernoHome)
for all its configuration settings. On MacOSX the location of this folder is:
/Users/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.
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").
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.
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".
bifernoctl.pid: is process id number of the bifernoctl process when started as sentinel process (see Appendix 1, Unix Manual Pages).
mod_biferno.log: is the log of the apache module.
None of the above files is modified when an update process is executed.
Table of Contents
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-[)
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.
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
|
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.
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.
The "Properties" window will appear. Select the "Home Directory" tab:
Now press the "Configuration" button, and in the "Application Configuration" window click on the "Add" button.
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:
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.
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
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.bfr
The configuration procedure for Apache is finished.
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
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.dll in other location than the default one, and the new path to BifernoISAPI.dll contains white spaces or special characters, IIS has problem locating the dll. Avoid spaces in BifernoISAPI.dll path 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.
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
|
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 On the contrary, in the |
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
directory to the [path to
Program
Files]\Biferno\BifernoHome\InactiveExtensions directory
and restart the Biferno Service.[path to Program
Files]\Biferno\BifernoHome\Extensions
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"):
To compile, respectively, the apache, oracle, mysql modules:
|
After the build process is finished the compiled binaries can be found in:
Distribution\Biferno_Win
![]() | Warning |
|---|---|
The following binaries: |
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:
(substitute [path to Program Files]\Biferno\BifernoHome
[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:
(substitute [path to Program Files]\Biferno\BifernoHome\bifernosvc.exe
[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
To uninstall Biferno follow these steps:
If you are using IIS stop the "IISAdmin" service.
Double-click the
biferno-
installer file and choose the Remove button.[version]-windows.exe
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)
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.
More information on reloading Biferno and flushing the cache can be found in the "Biferno: Language Guide" document.
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 . 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.[path to Program
Files]\Biferno\BifernoHome
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 .
This value is set internally by Biferno, don't modify it
manually.[path to
Program Files]\Biferno\BifernoHome\Biferno.exe
ServicePath: is the path of the biferno
service executable file, default is . This
value is set internally by Biferno, don't modify it
manually.[path to
Program Files]\Biferno\BifernoHome\bifernosvc.exe
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:
The service can be managed (as usual for Windows users) from the "Services" control panel inside "Settings\Control Panel\Administrative Tools\"
Table of Contents
The following manual pages describe the bifernoctl utility and the bifernod program under Linux and MacOSX.
bifernod — The biferno daemon
bifernod [
-v
] [
-i
] [
-f
]script_file
The bifernod daemon implements the Biferno web application programming language under Unix. The Biferno language is a new generation Web object-oriented scripting language that allows developers the rapid implementation of dynamic Web applications and of Web sites offering a high degree of user interactivity.
When started from the command line, bifernod will fork a
copy of itself to run in the background as a daemon (unless invoked with the
-i option, see Options). The
daemon will wait for an input page to be received from the Web server via
the Biferno plug-in. When an input page is received,
bifernod will process the input page and return the
corresponding output page to the Web server via the the Biferno plug-in.
-vPrint the version of the Biferno daemon and exit.
-iStarts bifernod in interactive mode. This prevents the daemon from running in the background. This option is meant to be used to debug startup problems, usually due to misconfiguration. When bifernod runs in interactive mode, it can be stopped by typing Ctrl-c.
-f script_file
Start bifernod, run the
script_file Biferno script and quit.
-pStart bifernod, read commands from standard input and quit.
bifernoctl — The biferno control program
bifernoctl { start | stop | restart | reload | flush | version }
bifernoctl
-s
[ start | stop ]
The bifernoctl is a front end to the bifernod daemon that allows the system administrator to control the Biferno daemon subsystem. The Biferno daemon subsystem consists of two processes, the bifernod Biferno language interpreter, and the bifernoctl process itself, which runs in the background monitoring the bifernod daemon and will restart it automatically if necessary. The bifernoctl command provides an administration interface for both processes (see Options). bifernoctl returns 0 (zero) if it could successfully complete its operation, a positive integer otherwise.
When invoked without options, bifernoctl
applies the command provided on the command line
to the bifernod daemon. The start,
stop, restart, reload,
and flush commands are supported.
startStarts bifernod.
stopStops bifernod.
restart
Restarts bifernod. This is equivalent to a
stop (if bifernod is running),
followed by a start.
reloadReloads bifernod. The effect of a reload is described in the Biferno user guide.
flushFlushes the bifernod cache.
versionPrint the version of the bifernod program and exit.
-s
When invoked simply with the -s option and no other
arguments on the command line, bifernoctl will start a
copy of itself to run in the background as a sentinel process monitoring
the health of the bifernod and restarting it
automatically if necessary.
One of the following commands can follow the -s option:
start
Starts bifernoctl as a sentinel process. Same as
-s with no command.
stopStops the bifernoctl sentinel process.
GNU Free Documentation License Version 1.2, November 2002 Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License. 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. 3. COPYING IN QUANTITY If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements". 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate. 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title. 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.