Biferno Installation and Administration Guide

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

1. Linux Installation
1. Requirements
2. Installing from the RPM Distribution
2.1. Main Package
2.2. Web Server Modules and Database Support Packages
2.3. Uninstalling and Upgrading
2.4. Notes
3. Installing from the Binary tar Archive
3.1. Configuration
3.2. Uninstalling
4. Compiling and Installing from Sources
4.1. Web Server Modules and Database Support Extensions
4.2. Configuration
5. Launching Biferno
6. Defining Environment Variables for Biferno
7. Verifying the Installation
7.1. Troubleshooting
8. Administration (BifernoCtl: Flush, Reload, Start and Stop)
9. Biferno on Linux: Advanced Concepts
2. MacOSX Installation
1. Requirements
2. Installing with the Apple Installer Package
2.1. Details about Apache
2.2. Upgrading
3. Compiling and Installing from Sources
3.1. Compilation
3.1.1. Project “bifernod
3.1.2. Project “apachemodule
3.1.3. Other projects
3.2. Installation
4. Launching Biferno
5. Defining Environment Variables for Biferno
6. Verifying the Installation
6.1. Troubleshooting
7. Uninstall
8. Administration (BifernoCtl: Flush, Reload, Start and Stop)
9. Biferno on MacOSX: Advanced Concepts
3. Windows
1. Requirements
2. Installing with the Windows Installer
2.1. Configuring IIS
2.2. Configuring Apache
2.3. Oracle Support
3. Verifying the Installation
3.1. Troubleshooting
4. Updating from a Previous Version
5. Compiling and Installing from Sources
6. Uninstalling
7. Administration (BifernoCtl: Flush, Reload, Start and Stop)
8. Biferno on Windows: Advanced Concepts
1. Unix Manual Pages
bifernod - The biferno daemon
bifernoctl - The biferno control program
2. GNU Free Documentation License

List of Figures

3.1. IIS: Default Web Site Property
3.2. IIS: Home Directory Panel
3.3. IIS: Application Configuration Panel
3.4. IIS: Add/Edit Application Extension Mapping
3.5. BifernoCtl: Start and Stop
3.6. BifernoCtl: Flush and Reload
3.7. Biferno Windows Service Registry

Chapter 1. Linux Installation

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.

1. Requirements

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.

2. Installing from the RPM Distribution

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.

2.1. Main Package

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-[biferno_version]-rpm_release_tag.i386.rpm. The filename for the rpm package for Biferno version 1.4.0, rpm release tag 1, would be biferno-[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 -iv biferno-[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:

  1. Biferno binaries are copied to /usr/bin.

  2. The Biferno home directory is copied to /home/BifernoHome.

  3. A user and a group called “biferno” are created.

  4. Biferno configuration information is added to the Apache configuration file. This information will be automatically removed when the package is uninstalled.

  5. 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.

2.2. Web Server Modules and Database Support Packages

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 -iv biferno-apachemodule-[vers].i386.rpm
$ rpm -iv biferno-oraclesupport-[vers].i386.rpm
   

2.3. Uninstalling and Upgrading

Biferno can be removed from the system using the rpm command as follows:

$ rpm -ev biferno-[vers].i386.rpm
   

This will also remove all configuration added by the automatic installation procedure from the system.

[Note]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.

2.4. Notes

[Tip]Expert Note: Manual Configuration with the rpm Package

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.

[Tip]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.

3. Installing from the Binary tar Archive

[Warning]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 -zxvf biferno-[vers].i386.tar.gz
  
  1. Now enter the directory you have just created.

    $ cd biferno-1.4.0/Linux/i386
        
  2. 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 ../../..
        
  3. 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
        
  4. Copy the BifernoHome directory to the target location:

    $ cp -r  BifernoHome/ /home
        
  5. 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)
        

3.1. Configuration

  1. 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/BifernoHome biferno
    	    
  2. Fix ownerships on /home/BifernoHome:

    $ chown -R biferno /home/BifernoHome
    $ chgrp -R biferno /home/BifernoHome
    	    
  3. Add biferno to the system startup profile:

    $ /sbin/chkconfig --add biferno
    	    
  4. 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.

  5. 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]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 AddModule has been added)

  6. 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.

3.2. Uninstalling

  1. If necessary, stop bifernod with /sbin/service biferno stop. Then remove it from the system startup profile with /sbin/chkconfig --del biferno.

  2. Remove the biferno user with /usr/sbin/userdel biferno. This will remove the bifernod group as well.

  3. Remove the biferno init script from the init.d directory with rm /etc/init.d/biferno.

  4. Remove the biferno home directory with rm -rf /home/BifernoHome.

  5. Remove the biferno configuration from the Apache configuration file (lines between the <IfDefine HAVE_BIFERNO> and </IfDefine> tags).

  6. Restart httpd to unload the bifernod module with /usr/sbin/apachectl restart.

4. Compiling and Installing from Sources

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]Note

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.

4.1. Web Server Modules and Database Support Extensions

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
   

4.2. Configuration

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.

5. Launching Biferno

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:

  1. Start the bifernod daemon and the bifernoctl monitoring process:

    $ /sbin/service biferno start
         
  2. Restart httpd:

    $ /usr/sbin/apachectl restart
         

6. Defining Environment Variables for Biferno

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.

7. Verifying the Installation

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.

7.1. Troubleshooting

  • 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.

8. Administration (BifernoCtl: Flush, Reload, Start and Stop)

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.

9. Biferno on Linux: Advanced Concepts

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.

Chapter 2. MacOSX Installation

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”.

1. Requirements

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.

2. Installing with the Apple Installer Package

Download the installer package, e.g. biferno-1.4.0-osx.dmg, (where 1.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-1.4.0-osx 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).

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:

  1. Biferno binaries are copied to /usr/bin.

  2. The Biferno home directory is copied to /Users/BifernoHome.

  3. A user and a group called biferno are created.

  4. Biferno configuration information is added to the Apache configuration file. This information will be automatically removed when the package is uninstalled.

  5. The Biferno initialization folder (called Biferno) is copied to the /Library/StartupItems directory to automatically start Biferno when the system is booted.

  6. 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".

2.1. Details about Apache

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.

2.2. Upgrading

Biferno can be upgraded to a new version by simply launching the Apple installer package for the new version as explained above.

3. Compiling and Installing from Sources

3.1. Compilation

To compile Biferno you need to install the Developer package from Apple (see http://developer.apple.com).

[Warning]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.

[Warning]Warning

On Tiger, some users reported a bug in Stuffit Expander duplicating files in the resulting uncompressed folder. To avoid this, use the system tool to untar the package (that is, simply double click on the file icon)

The XCode projects are in the folder "Projects". Open the projects and build them following these steps.

3.1.1. Project “bifernod

Open the project, set "BuildAll" as active target and build the project. This step builds the executables bifernod and bifernoctl)

3.1.2. Project “apachemodule

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

3.1.3. Other projects

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.

3.2. Installation

To install biferno after the compilation cd to folder biferno-[version]-osx.src and type:

sudo ./install.sh

[Warning]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.

4. Launching Biferno

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:

  1. 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
         
  2. Restart the httpd daemon in the Web Sharing Preference Panel or typing:

    $ sudo /usr/sbin/apachectl restart
         

5. Defining Environment Variables for Biferno

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.

6. Verifying the Installation

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.

6.1. Troubleshooting

  • 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:

    1. 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)

    2. decompress the file in a folder (i.e. /Users/John/Documents)

    3. type the following commands:

      	$ cd /Users/John/Documents/mysql-[version]
      	$ ./configure --enable-shared
      	$ make
      	
    4. 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>
    		

7. Uninstall

To uninstall biferno on MacOSX download the source package and run the script "uninstall.sh":

	$ cd [folder containing sources]
	$ sudo ./uninstall
	

8. Administration (BifernoCtl: Flush, Reload, Start and Stop)

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.

9. Biferno on MacOSX: Advanced Concepts

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.

Chapter 3. Windows

1. Requirements

Before installing "Biferno for Windows" on your computer, be sure to have, at least, the following configuration:

  • Windows Operating System: as of today Biferno has been tested only on Windows 2000, 2003, XP but it should run also on other versions. Biferno doesn't run on Windows 95-98 or ME.

  • Free space on Hard Disk >= 10MB.

  • Free RAM >= 24MB (this requirement depends on the maximum number of users for your web site).

  • One of the following Web servers:

    • Microsoft's IIS (Internet Information Service) or an ISAPI compatible web server

    • Apache for Windows. Only the Apache2 module is distributed as a binary. If you have a previous version of Apache (1.x.x) you should recompile the module with the includes and libraries files of that Apache version (see Section 5, “Compiling and Installing from Sources”). Besides, if you want to use Apache 2 as web server, note that Biferno requires at least version 2.0.41 of it.

2. Installing with the Windows Installer

Download the Biferno Windows installer (file biferno-[version]-windows.exe) from the net or copy it from another distribution media (CD-ROM) into a working directory. Now start the installer by double-clicking on the installer icon.

[Warning]Warning

If Microsoft's IIS is running on the machine where Biferno is being installed, you will need to stop it before proceeding with the Biferno installation. Failure to do so will cause the installation to fail, because of a file lock set by IIS on the BifernoISAPI.dll library. The installer will not be able to replace the BifernoISAPI.dll library if the library is present on disk (from a previous installation of Biferno) and is being used by IIS.

The installer installs the Biferno binaries and related files, creates the Biferno service as a Windows service and starts it. When the automatic installation procedure is completed, you will have to complete the installation manually by configuring your web server (either Microsoft's IIS or Apache) to use the appropriate Biferno module.

2.1. Configuring IIS

To configure IIS to use Biferno, open the "Computer Management" control (in Control Panel/Administration Tools) and right click on the "Services and Applications->Internet Information Services->Default Web Site" property. Choose the "Properties" item. Notice that we assume that the IIS software has been installed before installing Biferno.

Figure 3.1. IIS: Default Web Site Property

IIS: Default Web Site Property

The "Properties" window will appear. Select the "Home Directory" tab:

Figure 3.2. IIS: Home Directory Panel

IIS: Home Directory Panel

Now press the "Configuration" button, and in the "Application Configuration" window click on the "Add" button.

Figure 3.3. IIS: Application Configuration Panel

IIS: Application Configuration Panel

A configuration window will appear, where you will enter the following information:

  • Enter in the "Executable" column the path to the BifernoISAPI.dll dynamic library that has been installed by the Biferno installer in your inetsrv directory of the System32 directory. In Windows NT/2000/XP, this is the system32\inetsrv folder within the Windows folder where your Windows operating system has been installed.

  • Enter in the "Extension" column the .bfr suffix.

The information you entered will look similar to the following:

Figure 3.4. IIS: Add/Edit Application Extension Mapping

IIS: Add/Edit Application Extension Mapping

At this point restart the web service using "IIS Admin Service". You must restart also the "Internet Information Services" right clicking on the "Services and Applications->Internet Information Services->Default Web Site" property in "Computer Management" control and choosing start.

The configuration procedure for IIS is finished.

2.2. Configuring Apache

Copy the mod_biferno.so Apache module from the installation directory (by default: Program Files/Biferno/ApacheModule) into the Apache modules directory (by default: Apache Group/Apache2/modules).

Append the following lines to the Apache configuration file (by default: Apache Group/Apache2/conf/httpd.conf):

 
LoadModule biferno_module modules/mod_biferno.so 
AddHandler biferno-handler .bfr 
    
[Note]Note

If you are using a version of Apache prior to 2.x the configuration could be slighty different (the obsolete AddModule directive can be needed):

 
LoadModule biferno_module modules/mod_biferno.so 
AddHandler biferno-handler .bfr 
AddModule mod_biferno.c 
    

If you wish to specify the index.bfr as the default script, modify the DirectoryIndex directive in your Apache configuration file. The line containing the DirectoryIndex directive will be similar to the following:

DirectoryIndex index.html [some_other_index_names] 
   

and it should be modified to read:

DirectoryIndex index.html [some_other_index_names] index.bfr
   

The configuration procedure for Apache is finished.

2.3. Oracle Support

If you want to use the Oracle support that Biferno provides, you must manually copy the oracle_bfr.dll from the Program Files\Biferno\BifernoHome\InactiveExtensions directory to the Program Files\Biferno\BifernoHome\Extensions directory and restart the Biferno service.

3. Verifying the Installation

To verify the installation move the test.bfr file (from the BifernoHome directory) in the Web Server Document Root folder. From your browser invoke the URL:

http://[www.yourserver.com]/test.bfr
  

If the installation has been performed correctly the browser will show the following output:

Ok, Biferno was correctly installed
   

3.1. Troubleshooting

  • The request of page test.bfr fails:

    - check if the web server (IIS or Apache) is started. In particular, make request of a .html page. If the page is served, than skip this step, otherwise check the error log file of Apache ([Program Files]\Apache Group\Apache2/logs) or the System Event Log for IIS.

    - if the server is up (see previous step), be sure that the Biferno service (or the Biferno.exe application) is up and running. If you suspect problems on Biferno startup, it can be useful to debug it using the Biferno.exe application (instead of the service).

    - for IIS users: if you moved BifernoISAPI.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.

4. Updating from a Previous Version

To update from a previous version, it is safe to use the file "biferno-[version]-windows.exe".

[Warning]Warning

If Microsoft's IIS is running on the machine where Biferno is being installed, you will need to stop it before proceeding with the Biferno installation. Failure to do so will cause the installation to fail, because of a file lock set by IIS on the BifernoISAPI.dll library. The installer will not be able to replace the BifernoISAPI.dll library if the library is present on disk (from a previous installation of Biferno) and is being used by IIS.

If the version of Biferno you want to install is already installed, the installer will prompt you using a dialog with a button that allows remove the current installation before performing a new installation from scratch. Click the "Remove" button and then re-execute a clean installation (note that for the Windows installer "beta" version are considered equal, for example 1.0b4 is the same as 1.0b5).

[Note]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]Warning

The bifernoadmin, Utils and Man folders are completely replaced when an installation is updated. Therefore it is not safe to use any of these folders to store your own files.

On the contrary, in the Extensions folder only files in the Biferno distribution are replaced leaving untouched all files created by the user. It is perfectly OK to use the Extensions folder to store your own extensions.

If you are using the Oracle support that Biferno provides, you must manually update it. To do the update, copy the oracle_bfr.dll from the [path to Program Files]\Biferno\BifernoHome\InactiveExtensions directory to the [path to Program Files]\Biferno\BifernoHome\Extensions directory and restart the Biferno Service.

5. Compiling and Installing from Sources

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]Note

Before compiling, the following search includes path must be added to your VisualC environment (menu "Tools option->Directories"):

  • [path to Biferno Sources]\XLIB\XLIB\C_INCLUDE

  • [path to Biferno Sources]\XLIB\XLIB\C_INCLUDE\MD5 (this is needed from Biferno version 1.1)

  • [path to Biferno Sources]\XLIB\XLIBWIN\C_INCLUDE

  • [path to Biferno Sources]\SOURCE\CLASSES\C_INCLUDE

  • [path to Biferno Sources]\SOURCE\SOURCES\C_INCLUDE

  • [path to Biferno Sources]\XLIB\XLIBHTTP\C_INCLUDE

  • [path to Biferno Sources]\PROJECTS\RESOURCES

To compile, respectively, the apache, oracle, mysql modules:

  • [path to program files]\APACHE GROUP\APACHE2\INCLUDE

  • [path to oracle home]\ORA81\OCI\INCLUDE

  • [path to program files]\MYSQL\INCLUDE

After the build process is finished the compiled binaries can be found in:

Distribution\Biferno_Win
  
[Warning]Warning

The following binaries: mod_biferno.so (Apache module), mysql_bfr.dll and oracle_bfr.dll are not compiled by default because, generally, they need third-party includes and libraries not available to all developers. To build them, modify the dependencies of the "Build" project (from the menu "Project->Dependencies") before building, or open directly the single projects: Projects\VisualC\BifernoApache\BifernoApache.dsp, External\mysql\mysqlVC\mysqlVC.dsp and External\oracle\oracleVC\oracleVC.dsp).

To install the version of Biferno just compiled follow these steps:

  • Create BifernoHome: create a folder named Biferno in your "Program Files" folder and move the folder Distribution\Biferno_Win\BifernoHome inside it.

  • Set the BifernoHome registry value: open the regedit application and add the following key to the Registry: HKEY_LOCAL_MACHINE\SOFTWARE\Tabasoft\Biferno\BifernoHome as a string with value: [path to Program Files]\Biferno\BifernoHome (substitute [path to Program Files] with the real name of the "Program Files" folder on your system, e.g. C:\Program Files\Biferno\BifernoHome)

  • Configure the web server:

    • IIS: copy the file Distribution\Biferno_Win\ISAPIModule\BifernoISAPI to the your "inetsrv" directory of System32 directory. In Windows NT/2000/XP, this is the system32\inetsrv folder within the Windows folder where your Windows operating system has been installed. Then configure the module as explained in Section 2.1, “Configuring IIS”

    • Apache: Configure the module as explained in Section 2.2, “Configuring Apache” (the module, after compilation, is in Distribution\Biferno_Win\ApacheModule)

  • Add the service registry: if you want to use Biferno as a service you must add the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\bifernosvc to the registry (see Section 8, “Biferno on Windows: Advanced Concepts”). To do so double click the file BifernoSvc.reg. A bifernosvc key will be added in: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ open the key (with regedit) and fill the value of ImagePath with: [path to Program Files]\Biferno\BifernoHome\bifernosvc.exe (substitute [path to Program Files] with the real name of the "Program Files" folder on your system). See, as an example, the figure Figure 3.7, “Biferno Windows Service Registry”

  • Start IIS and BifernoService

  • Copy the folders bifernoadmin, Utils and Man into [path to Program Files]\Biferno\BifernoHome

6. Uninstalling

To uninstall Biferno follow these steps:

  • If you are using IIS stop the "IISAdmin" service.

  • Double-click the biferno-[version]-windows.exe installer file and choose the Remove button.

  • If you are using IIS, delete the IIS configuration as explained in Section 2.1, “Configuring IIS”

  • If you are using Apache, delete the Apache configuration as explained in Section 2.2, “Configuring Apache”, and remove the mod_biferno.so module from the Apache directory (by default: Apache Group/Apache2/modules)

7. Administration (BifernoCtl: Flush, Reload, Start and Stop)

The Bifernoctl application, which is launched via the Biferno program group in the Windows "Start" menu, allows to control the Biferno server. The application allows to start and stop the Biferno server in console or service mode, to reload Biferno and to flush the Biferno cache.

Figure 3.5. BifernoCtl: Start and Stop

BifernoCtl: Start and Stop

Figure 3.6. BifernoCtl: Flush and Reload

BifernoCtl: Flush and Reload

More information on reloading Biferno and flushing the cache can be found in the "Biferno: Language Guide" document.

8. Biferno on Windows: Advanced Concepts

This paragraph explains the details of Biferno operations on the Win32 operating system.

On the Windows operating system, Biferno is implemented as a web server plugin (called BifernoISAPI.dll for IIS, mod_biferno.so for Apache). The plugin communicates (via TCP/IP sockets) with a local multithreaded server application (called Biferno.exe or bifernosvc.exe). The plugin intercepts requests of pages ending in ".bfr" to the web server (using ISAPI or AP callbacks), and passes the page requests to the Biferno application. The Biferno application responds to plugin requests and can run in interactive console mode (Biferno.exe) or as a system service (bifernosvc.exe).

The Web server must be informed by configuration of the existence and location of the Biferno plugin (see Section 2.1, “Configuring IIS” or Section 2.2, “Configuring Apache”).

Biferno uses a special folder (called BifernoHome) for all its configuration settings. On Windows this location of this folder is choosen at installation time. The default is :

 
   [path to Program Files]\Biferno\BifernoHome 

This folder contains, among others, the folllowing folders and files:

  • bifernoadmin folder: contains all bifernoadmin source files. If this folder is not present, Biferno will work correctly, but bifernoadmin will not be accessible (the bifernoadmin application is described in the "Biferno: bifernoadmin Guide" document).

  • Utils folder: contains a set of Biferno utilities for script development. The presence of this folder is not mandatory for Biferno to be fully functional.

  • Man folder: contains the man pages in xml format as displayed in the Biferno Reference On Line (see "Biferno: bifernoadmin Guide"). If this folder is not present Biferno will function correctly but the Reference on line will not have field descriptions.

  • Extensions folder: is the folder containing all the BAPI extensions (classes and functions written in the C language plug-ins). If this folder is not present Biferno creates it at the first run and will continue to operate normally, but no extensions will be loaded.

  • Biferno.exe file: is the executable of the Biferno Console application

  • bifernosvc.exe file: is the executable of the Biferno Service application

  • BifernoCtl.exe file: the application BifernoCtl (see Section 7, “Administration (BifernoCtl: Flush, Reload, Start and Stop)”).

In addition to the above, the following files are automatically created by Biferno in BifernoHome folder at the first run:

  • biferno.conf: is the file for the Biferno advanced performance settings (see the Appendix in "Biferno: Language Guide").

  • Biferno.config.bfr: the config file for the main application (see the chapter on applications in "Biferno: Language Guide").

  • Biferno.pid: contains the process id of the Biferno application currently running (Console or Service).

  • bifernoctl.log: the log file of BifernoCtl.

  • BifernoServer.log: the log file of Biferno Console.

  • BifernoServer.log_CANT_INIT_BIFERNO_TWICE: this file is created if there has been an attempt to start Biferno Console twice.

  • BifernoService.log: the log file of Biferno Service.

  • BifernoService.log_CANT_INIT_BIFERNO_TWICE: this file is created if there has been an attempt to start Biferno Service twice.

  • BifernoSmtp.doing: ths file is for Biferno internal use (is used to syncronize the Biferno SMTP (Simple Mail Transfer Protocol) asyncronous background thread).

  • BifernoSmtp.log: the log file for the Biferno SMTP (Simple Mail Transfer Protocol) threads.

  • BifernoSmtp.que and BifernoSmtp.que.temp: are files used by Biferno for the Biferno SMTP (Simple Mail Transfer protocol) asyncronous background thread.

  • Persistent folder: used for persistent variables storage (text and binary file), see the chapter on applications in "Biferno: Language Guide".

None of the above files is modified when an update process is executed.

Biferno uses the Windows registry database to store information about the current environment. Biferno registries can be found under the key:

 
HKEY_LOCAL_MACHINE\SOFTWARE\Tabasoft\Biferno
  

In particular the following registry are used:

  • BifernoHome: contains the path of BifernoHome folder, default is [path to Program Files]\Biferno\BifernoHome. Don't modify this value. If you want to move the BifernoHome to a different location, uninstall Biferno and reinstall it in the new location.

  • ExeMode: contains a string indicating the mode Biferno is running in. Possible values are SERVICE or CONSOLE. This value is set internally by Biferno, don't modify it manually.

  • ConsolePath: is the path of the biferno console executable file, default is [path to Program Files]\Biferno\BifernoHome\Biferno.exe. This value is set internally by Biferno, don't modify it manually.

  • ServicePath: is the path of the biferno service executable file, default is [path to Program Files]\Biferno\BifernoHome\bifernosvc.exe. This value is set internally by Biferno, don't modify it manually.

  • Port: contains the number of the TCP/IP port used for the communication between the web module and the Biferno (service or console), default is 4999. Users can modify this value (restart Biferno and the Web Server after modification).

  • CtlPort: unused.

The biferno service registry can be found under the key:

 
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\bifernosvc
  

and looks as in the following picture:

Figure 3.7. Biferno Windows Service Registry

Biferno Windows Service Registry

The service can be managed (as usual for Windows users) from the "Services" control panel inside "Settings\Control Panel\Administrative Tools\"

Appendix 1. Unix Manual Pages

Table of Contents

bifernod - The biferno daemon
bifernoctl - The biferno control program

The following manual pages describe the bifernoctl utility and the bifernod program under Linux and MacOSX.

Name

bifernod — The biferno daemon

Synopsis

bifernod [ -v ] [ -i ] [ -f script_file ]

Description

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.

Options

-v

Print the version of the Biferno daemon and exit.

-i

Starts 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.

-p

Start bifernod, read commands from standard input and quit.

Environment

-

Files

   /usr/bin/bifernod
   /home/Bifernohome/
  

Name

bifernoctl — The biferno control program

Synopsis

bifernoctl { start | stop | restart | reload | flush | version }

bifernoctl -s [ start | stop ]

Description

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.

Options

no options

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.

start

Starts bifernod.

stop

Stops bifernod.

restart

Restarts bifernod. This is equivalent to a stop (if bifernod is running), followed by a start.

reload

Reloads bifernod. The effect of a reload is described in the Biferno user guide.

flush

Flushes the bifernod cache.

version

Print 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.

stop

Stops the bifernoctl sentinel process.

Files

    /usr/bin/bifernoctl
   

See Also

bifernod (8)

Appendix 2. GNU Free Documentation License

   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.