Instructions for Installing Emoncms on NAS4Free / FreeBSD file server


I am a relatively new member to the Open Energy Monitor group, but I wanted to share the learning I have done in getting the Emoncms software to run on a NAS4Free / FreeBSD file server. NAS4Free is an open source project to write software that runs on FreeBSD to provide an easy to setup and run file server on light hardware. FreeBSD is a Unix derivative similar to Linux, but it is not based on the Debian kernel, instead forking off earlier in that tree. It is mostly used in web servers and the like as a fairly secure and light client.

The NAS4Free software was originally worked on under the FreeNAS title, but switched names in the past few years. The software uses a web interface to setup and monitor the file server remotely, which makes setting up network services like CIFS/Samba file sharing (MS Windows network drives) really easy. It is also designed to be compatible with older hardware you might have sitting at home, and it can run in an 'embedded' mode where you install and run the OS off of a USB memory stick, and keep all of your hard drive space available for network storage. The challenge that adds is that most of the OS runs in a RAM disk to minimize read/write to the flash memory, which results in extra FreeBSD software installed not being retained during a reboot.

I have been using the NAS4Free software for a home file server for many years, and wanted to use it for running a local Emoncms server, but was unsure if it would work or not. I am an engineer by trade and an avid computer user, but my knowledge of FreeBSD or Linux was very limited as once I setup the file server using the web management tool, I pretty much left it alone. I used a variety of guides on the web on how to setup FreeBSD jails (secure VM like processes), how to install AMP (Apache/MySQL/PHP) on FreeBSD, and how to troubleshoot it. What follows is what worked for me to get Emoncms fully operational and in a more secure FreeBSD jail under NAS4Free. It was installed using methods that allow it to be retained through reboot, while retaining the robustness and easy upgrade path that the embedded install is designed for. It may not be the best way, but it worked for me. I welcome any comments or recommendations to add to the collective knowledge.

Here are the steps:

1. Install NAS4Free on the computer

This is done by creating a LiveCD that will boot into a FreeBSD loader and give you options to install it onto a disk or USB memory stick. In my case I used a small SSD, partitioned into three partitions (OS/swap/data), but you could easily do this using the basic single OS partition to a memory stick, and mounting a separate data drive for Emoncms. Once NAS4Free is installed, reboot the server and log into it using your web browser.

In the NAS4Free web management tool

enable the SSH server, be sure to check option to allow login as root

mount at least a single drive to contain the FreeBSD jail and the Emoncms software. I refer to this mounted drive as /mnt/{your storage drive name} in the directions that follow.


Install 'The Brig' NAS4Free extension to create and manage FreeBSD jails


SSH to NAS4Free server, login as root with WebGUI password

mkdir /mnt/{your storage drive name}/thebrig



chmod 755

sh /mnt/{your storage drive name}/thebrig

Reboot server


Initialize The Brig

Log into the NAS4Free WebGUI and click on the new Extensions menu to enter The Brig. The first time you go there it will walk you through the setup. Download the the base and lib32 tarballs needed (the FreeBSD OS) to install a full verion of FreeBSD in the new jail we are creating.


Create the jail

Click to create a new FreeBSD jail with the following options:

Jail number: 1 (Default is 1 for your first jail)

Jail Name:your choice but I called my emon

Jail Type: Full

Jail Interface: LAN

Jail IP address: choose an IP address for this jailed version of FreeBSD to interact with the network on. I don't think allowing this to be set dynamically will work, as elsewhere in the directions you will need to type this IP into various configuration files. The file server will have two IP addresses on the network for one physical connection. One will be for the base NAS4Free install, one for the FreeBSD running Emoncms in the jail. In my case this was

Jail Start on boot: Check

Source from Archive: Check both the base and lib32 versions

Once complete, reboot, go back to this web page and verify that the jail is running.

2. Install AMP (Apache/MySQL/PHP) in the jail

SSH to the original NAS4Free server just like before

Once in, verify the status of the jail by typing 'jls' – you should see your jail listed and with the IP address you gave it.

Enter into the FreeBSD running in the jail using 'jexec 1 csh' (1 is the jail number if you have more than one jail). All of the remaining commands are to be entered in the FreeBSD running in the jail.


Install Nano text editor

not needed but I found it easier to use than the built in one

pkg_add -r nano

Install Apache 2.2

pkg_add -r apache22

This will take awhile and occasionally prompt you with various install options. Always choose the default.


Add line to rc.conf to get apache to start at boot

echo 'apache22_enable="YES"' >> /etc/rc.conf


Edit hosts file to let apache know what hostname it has

nano /etc/hosts

edit line with IP address to read – localhost.{your jail name}.local

add line at bottom with your jail IP and your jail name (My line reads: emon.local)

{your jail IP address} {your jail name}.local

Save and exit

Start Apache server using 'apachectl start' command.

Verify Apache web server is running by pointing a web browser at your jailed FreeBSD IP ( in my case). If it is running you will see “It works!” in your web browser.

Install MySQL

pkg_add -r mysql55-server

echo 'mysql_enable="YES"' >> /etc/rc.conf

/usr/local/etc/rc.d/mysql-server start

/usr/local/bin/mysqladmin -u root password '{your MySQL password}'

Install PHP

I could only get this to work using the ports distribution instead of the package distribution

portsnap fetch extract

cd /usr/ports/lang/php5 && make config – choose option to include apache module

make install clean

Install PHP extensions

cd /usr/ports/lang/php5-extensions && make config

Select Gettext, mysql, and mysqli support options. I don't know if MySQLi extensions are needed, but I selected it to make sure.

make install clean


Edit httpd.conf file for PHP

nano /usr/local/etc/apache22/httpd.conf

Search for AddType section – and add the following two lines

AddType application/x-httpd-php .php

AddType application/x-httpd-php-source .phps

Search for DirectoryIndex line and change from:

DirectoryIndex index.html


DirectoryIndex index.php index.html

search for section starting with:

<Directory "/usr/local/www/apache22/data">

and scroll down to line:

AllowOverride None

and change to:

AllowOverride All

This is the Enable Mod Rewrite setting needed for Emoncms


Create php.ini file to list your timezone (from Emoncms forum posts on how to correct PHP errors in Emoncms)

touch /usr/local/etc/php.ini

nano /usr/local/etc/php.ini

Add a line that reads:

date.timezone ="America/New_York"

change to your timezone, list of zones available at


Restart Apache

apachectl restart


Test PHP is working and attached to Apache

Create a test php file with the following command:

echo "<? phpinfo(); ?>" >> /usr/local/www/apache22/data/test.php

and then in a browser on a computer, go to the web page {your jail IP address}/test.php

You should see a long web page listing all of the settings and extensions in PHP. If not, or if your web browser wants you to view a PHP file, then PHP and Apache are not linked.

3. Install Emoncms

Picking up the directions posted on for a Linux install at step 6, with some slight modifications as the file locations and names were sometimes different.

Install git

pkg_add -r git

Install Emoncms

cd /usr/local/www/apache22/data

git clone

create mysql database

mysql -u root -p

mysql> CREATE DATABASE emoncms;

mysql> exit

Set emoncms database settings

cd /usr/local/www/apache22/data/emoncms

cp default.settings.php settings.php

nano settings.php

enter in mysql username and password from earlier

In an internet browser, load emoncms:

browse to


Once that was all complete I was able to follow the directions on the Emoncms website to post some dummy data to the site and navigate the menus to create a few feeds. I don't have any hardware yet, but will be ordering it shortly. If I find anything new that comes up and the directions need changing, I will correct the post with any updates. I hope this information is helpful to some who may want to combine a file server and an Emoncms server in one appliance. I had initally planned on setting up a file server with Ubuntu so the Emoncms work would be easy, but found getting Ubuntu to be as pain free as the NAS4Free software wasn't happening. If you haven't considered using the NAS4Free software for your file server, I highly recommend it.

Sorry for the long post, and if you read to this far, thanks for your time.



Paul Reed's picture

Re: Instructions for Installing Emoncms on NAS4Free / FreeBSD file server

Excellent tutorial, thanks for posting Dan.


Robert Wall's picture

Re: Instructions for Installing Emoncms on NAS4Free / FreeBSD file server

This deserves to go into the emoncms installation notes - I've flagged it to Trystan.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.