Table of Contents
There are two methods to install Biferno under MacOSX:
Use the fully automated installation and configuration procedure based on the Apple installer Biferno package.
Compile and install from the Biferno source code tar archive.
We strongly recommend installing via the Apple Installer package as described in Section 2, “Installing with the Apple Installer Package”. The steps to install from the source code tar archive is described in Section 3, “Compiling and Installing from Sources”.
Before installing Biferno for MacOSX on your computer, be sure to have, at least, the following configuration:
System version 10.2 (Jaguar) or greater is required to correctly run Biferno on the MacOSX platform.
Free space on Hard Disk >= 10MB.
Free RAM >= 24MB (this requirement depends on the maximum number of users for your web site).
The Apache Web server (version 1.x or 2.x). If you want to use Apache 2 as web server, note that Biferno requires at least version 2.0.41 of it.
Verify that your Apache binary has been compiled with the
--enable-module=so option enabled that supports the
use of external DSO (Dynamic Shared Object) modules. To check if this
is the case use the command:
$ httpd -l
and verify that the mod_so string appears in
the list printed on the screen.
Download the installer package, e.g.
biferno-,
(where 1.4.0-osx.dmg1.4.0 should be replaced by the
version of the downloaded software) from the net or copy it from another
distribution media (CD-ROM). Double-click on the .dmg file icon to
mount the disk image on your
desktop.
A disk icon named
biferno- is
now on your desktop. Double-click this icon to open a window showing the
package file and double click the package file to start installation
(recent versions of Safari should handle all these actions for you).
1.4.0-osx
After supplying your password to the installer, accepting the license agreement and choosing the destination disk, the automated installation procedure will install and configure Biferno for operation on your machine. The procedure is fully automatic and will go through the following steps:
Biferno binaries are copied to /usr/bin.
The Biferno home directory is copied to /Users/BifernoHome.
A user and a group called biferno are created.
Biferno configuration information is added to the Apache configuration file. This information will be automatically removed when the package is uninstalled.
The Biferno initialization folder (called
Biferno) is copied to the
/Library/StartupItems directory to automatically
start Biferno when the system is booted.
Some other collateral tasks as the installation of the Biferno Control Panel in the "System Preference" application
At the end of the installation process you are asked to restart the computer. You can avoid this if you restart Apache and start Biferno manually. Apache can be restarted in "System Preference -> Sharing -> Web sharing" and Biferno can be started from System Preference -> Biferno".
The installer needs to know the version of apache installed on your computer
in order to choose the correct biferno-apache module to install.
It obtain the version of apache using the command:
httpd -v. The module is then copied in the folder whose
location is in the output of command: apxs -q LIBEXECDIR.
Then the installer adds the biferno LoadModule and
AddHandler directive
to the httpd config file found in the field "SERVER_CONFIG_FILE" of the output
of command: httpd -V.
To compile Biferno you need to install the Developer package from Apple (see http://developer.apple.com).
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.
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.
Open the project, set "BuildAll" as active target and build the project.
This step builds the executables bifernod and bifernoctl)
apachemodule: Open the project and build it. This step builds the module of biferno for Apache.
Depending on the version of Apache you are using you may want to change the setting of the directory containing the apache includes (Edit Project Setting, tab Build, Setting "User Header Search Path"). Current include path is "$(SDKROOT)/usr/include/httpd"
An alternative to XCode to compile the apache module is the "apxs" terminal command.
Open a terminal window, cd to the folder Projects/ApxsModule then type "make".
The command builds the biferno apache module using the tool apxs in canonical location. To use a different apxs file type:
make APXS=[path to apxs]
For example if you have installed a version of apache 2.2 in the folder /usr/local/apache22 and want a module for that version of apache type:
make APXS=/usr/local/apache22/bin/apxs
The projects listed here are recommended but not mandatory for a correct functioning of Biferno.
externals (target BuildAll): set "BuildAll" as active target and build project (builds some useful extensions)
BifernoPanel: builds the preference pane to administer Biferno
additional:
this project contains some targets to build additional extensions of Biferno
- mysql:
builds the extension "mysql_bfr.so" to call MySQL from Biferno. You must have mysql installed on your machine.
The target "mysql" searches the mysql include headers in: "/usr/include/mysql" or "/usr/local/mysql/include". If you have the MySQL include headers in some other location, in XCode set the active target to "mysql", then change the value of: Edit Active Target "mysql" -> Build -> "User Header Search Path"
- postgres:
builds the extension "postgres_bfr.so" to call PostgreSQL from Biferno. You must have PostgreSQL installed on your machine.
The target "postgres" searches the postgres include headers in: "/usr/include/pgsql" or "/usr/local/pgsql/include". If you have the PostgreSQL include headers in some other location, in XCode set the active target to "postgres", then change the value of: Edit Active Target "postgres" -> Build -> "User Header Search Paths"
The target "postgres" searches for libraries in path: "/usr/local/pgsql/lib". If you have the PostgreSQL libraries in some other location, in XCode set the active target to "postgres", then change the value of: Edit Active Target "postgres" -> Build -> "Library Search Paths"
- pop3:
builds the extension "pop3_bfr.so" that implements the POP protocol (Post Office Protocol) in Biferno. The extension needs the libspopc files (http://brouits.free.fr/libspopc/).
The target "pop3" searches the libspopc include header "libspopc.h" in: "/usr/include". If you have the libspopc include header in some other location, in XCode set the active target to "pop3", then change the value of: Edit Active Target "postgres" -> Build -> "User Header Search Paths"
The target "pop3" needs also the libspopc source files: format.c objects.c parsing.c queries.c session.c get them from the libspopc site (above) and put it in a folder called "libspopcsrc" in the root of biferno-[vers]-osx.src.
To install biferno after the compilation cd to folder biferno-[version]-osx.src and type:
sudo ./install.sh
To perform the above steps you will need root privileges. If the root user is not active on your machine, it can be activated by using the sudo passwd root command. You will be asked to supply a new password for the root user. Keep this password secret and remember that the root user can execute any administrative operation on your system. For more details on the activation of the user root on MacOSX look here.
Biferno is not started automatically after the installation is completed, because it is necessary to restart the Apache server before the installation can be fully operational. Restarting Apache should be done manually at a time suitable to the system administrator as it will disrupt operations on a live web server.
To make Biferno operational, you can either restart the machine, or perform the following steps:
Start the bifernod daemon and the bifernoctl monitoring process in the System Preference Biferno Panel or typing:
$sudo /usr/bin/bifernod$sudo /usr/bin/bifernoctl -s
Restart the httpd daemon in the Web Sharing Preference Panel or typing:
$ sudo /usr/sbin/apachectl restart
Environment variables which must be defined in the startup environment for the Biferno daemon, such as the variables PATH or LD_LIBRARY_PATH (used by the system to locate the dynamic libraries) must be defined in a file called bifernodefs.sh.
This file must be located in /Library/StartupItems/Biferno, and its content, if the file exists on disk, are sourced from the biferno startup script (/Library/StartupItems/Biferno/Biferno).
For example, to add the /mylibraries directory to the default search path of dynamic libraries (LD_LIBRARY_PATH), one might create the file /Library/StartupItems/Biferno/bifernodefs.sh (readable by the startup user, root) and write the following in it:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/mylibraries
You should not modify the startup script itself, as the modifications may be overwritten by the installation of future versions.
At this point, you should have completed the installation procedure and have restarted your web server. Now it is time to test the installation.
In order to do this, you will need to copy the test.bfr
file from the distribution (from the BifernoHome
directory) into the root directory of your web server. You should also make
sure that Biferno is running.
Finally, from your favorite browser, invoke the URL:
http://www.yourserver.com/test.bfr
If the installation has been performed correctly, the browser window will show the following output:
Ok, Biferno was correctly installed
This confirms that the test.bfr page you
requested was correctly interpreted by bifernod.
The request of page test.bfr fails:
- the web server (Apache) is not started. Check the error log file of
Apache to check the reason (usually in /private/var/log/httpd/error_log).
The page test.bfr returns the following text:
If you are seeing this, Biferno was not correctly installed. Make sure the web server is correctly configured to handle .bfr files.
In this case the web server is responding to requests but doesn't invoke the
mod_biferno.so for ".bfr" requests.
Check the configuration of the httpd.conf file.
The page test.bfr returns the following text:
ERROR: 2 (No such file or directory) Biferno is down (file /tmp/biferno.str not found)
or
ERROR: 61 (Connection refused)
- the demon bifernod is not started. The web server is running and invokes correctly the mod_biferno.so but the module can't reach the biferno demon and send it requests. To debug bifernod startup, start it in interactive mode using the command: bifernod -i.
bifernod -i immediately exits with message:
Exiting... Permission denied
- bifernod has not sufficient privileges to write in BifernoHome folder. Try with the command (as root): chown -R biferno.biferno /home/BifernoHome/
bifernod -i exits with message:
Exiting... Address already in use
- try to remove the pipe name file with command: rm /tmp/biferno.str
Although you have installed mysql on your machine, the load of "mysql_bfr.so" extension fails with message:
Can't Initialize mysql client lib: NSObjectFileImageInappropriateFile (while looking for: libmysqlclient.dylib)
The installer of MySQL on MacOSX does not contain the library "libmysqlclient.dylib". Nevertheless you need it in order to use MySQL with Biferno on MacOSX.
The following note explain how to build and install it:
download the source of MySQL: the source package can be found in the section "Source downloads" of the mysql download page (remember to choose the same version ([version]) of mysql you have installed on your machine)
decompress the file in a folder (i.e. /Users/John/Documents)
type the following commands:
$cd /Users/John/Documents/mysql-[version]$./configure --enable-shared$make
When the make command has completed you will find the lib in the folder:
/Users/John/Documents/mysql-[version]/libmysql/.libs/libmysqlclient.dylib.
To complete the operation copy it to the default lib folder (as root):
$cd /Users/John/Documents/mysql-[version]/libmysql$sudo cp .libs/libmysqlclient.dylib /usr/lib
After this operation Biferno should load the library and initialize the mysql extension correctly.
To work with bifernoadmin (see Manual) some versions of Apache require this directive:
<Directory /home/BifernoHome/bifernoadmin> Options None AllowOverride None Order deny,allow Allow from all </Directory>
To uninstall biferno on MacOSX download the source package and run the script "uninstall.sh":
$cd [folder containing sources]$sudo ./uninstall
Administration under MacOSX is performed via the Biferno System Preference Control Panel. Additionally, as in Linux, the bifernoctl and the bifernod commands can be used. They are described in Appendix 1, Unix Manual Pages.
This paragraph explains the details of Biferno operations on MacOSX operating system.
On the MacOSX operating system, Biferno is implemented as an Apache module (called mod_biferno.so) communicating (using Pipe Names) with a local multithreaded
daemon application (called bifernod). The module intercepts requests of pages
ending in ".bfr" to the web server, and
passes the page requests to the bifernod. bifernod
responds to module requests. bifernod can run also in interactive mode if invoked with the command: bifernod -i.
The Web server (Apache) must be informed by configuration of the existence and location of the mod_biferno.so module.
Biferno uses a special folder (called BifernoHome)
for all its configuration settings. On MacOSX the location of this folder is:
/Users/BifernoHome.
This folder contains, among others, the folllowing folders and files:
bifernoadmin folder: contains all bifernoadmin source files. If this folder is not present, Biferno will work correctly, but bifernoadmin will not be accessible (the bifernoadmin application is described in the "Biferno: bifernoadmin Guide" document).
Utils folder: contains a set of Biferno utilities for script development. The presence of this folder is not mandatory for Biferno to be fully functional.
Man folder: contains the man pages in xml format as displayed in the Biferno Reference On Line (see "Biferno: bifernoadmin Guide"). If this folder is not present Biferno will function correctly but the Reference on line will not have field descriptions.
Extensions folder: is the folder containing all the BAPI extensions (classes and functions written in the C language plug-ins). If this folder is not present Biferno creates it at the first run and will continue to operate normally, but no extensions will be loaded.
In addition to the above, the following files are automatically created by Biferno in BifernoHome folder at the first run:
biferno.conf: is the file for the Biferno advanced performance settings (see the Appendix in "Biferno: Language Guide").
Biferno.config.bfr: the config file for the main application (see the chapter on applications in "Biferno: Language Guide").
BifernoServer.log: the log file of Biferno Console.
BifernoServer.log_CANT_INIT_BIFERNO_TWICE: this file is created if there has been an attempt to start Biferno Console twice.
BifernoSmtp.doing: ths file is for Biferno internal use (is used to syncronize the Biferno SMTP (Simple Mail Transfer Protocol) asyncronous background thread).
BifernoSmtp.log: the log file for the Biferno SMTP (Simple Mail Transfer Protocol) threads.
BifernoSmtp.que and BifernoSmtp.que.temp: are files used by Biferno for the Biferno SMTP (Simple Mail Transfer protocol) asyncronous background thread.
Persistent folder: used for persistent variables storage (text and binary file), see the chapter on applications in "Biferno: Language Guide".
bifernoctl.pid: is process id number of the bifernoctl process when started as sentinel process (see Appendix 1, Unix Manual Pages).
mod_biferno.log: is the log of the apache module.
None of the above files is modified when an update process is executed.