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.
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.
It is possible to use rpm only to install the
binaries and the BifernoHome directory, and skip the automatic
post-installation procedure that comes with the
rpm package file. If you do this, you will
be on your own to correctly configure your system by a manual
procedure, which is described in Section 3.1, “Configuration”. Use this rpm command
to install the software, but skip automatic configuration:
$ rpm -i --noscripts biferno-[vers].i386.rpm
We advise to do this only if you are an experienced system administrator.
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.
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
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 AddModule has been added)
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.
The .rpm .src installer create a file named biferno-[versione]-Linux.src.tar.gz in the location:
[default source redhat folder]/SOURCES (the default for
[default source redhat folder] is /usr/src/redhat/). Besides it creates the file
biferno.spec in the location [default source redhat folder]/SPECS.
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.