Developing Packages

From PFSenseDocs

pfSense Packaging System

The basic idea behind pfSense packaging system is to install the normal FreeBSD packages, but keep the configuration inside the pfSense xml. This is achieved by creating the config file of application from scratch from xml duing installation and when it is changed in web interface. pfSense provides infrastructure to create the web interface and to store it in it's xml config. The package writer is expected to convert the data from xml to the native format of the application.

Creating a Local Repository.

To test local packages you need to create a local repository of packages. The local repository can be any web server accessible from wan interface with 2 main subdirectories. They are packages and pfSense. packages contain the main package manifest file pkg_config.xml. This also has config subdirectory for package specefic configuration files. The pfSense directory has xmlrpc code. Get the xmlrpc code from http://www.pfsense.com/xmlrpc.tgz and untar it in the directory. To change the default repository directory from pfsense.com to your webserver, edit the /etc/inc/globals.inc and change xmlrpcbaseurl to your repository. Now click the System -> Packages from the pfsense web interface and you should see packages from your local repository. You are set to go now.

Package System

pfSense package are composed of

 Manifest File
 Package Configuration files
 Actual Binaries from FreeBSD

Manifest File

Manifest file is the packages/pkg_config.xml It contains list of packages available for installation and some basic information about packages. The format of manifest xml is as follows:

 <pfsensepkgs>
 <packages> 
 <package>
 <name></name>
 <website></website>
 <descr></descr>
 <category></category>
 <config_file></config_file>
 <depends_on_package_base_url></depends_on_package_base_url>
 <depends_on_package></depends_on_package>
 <version></version>
 <status></status>
 <maintainer></maintainer>
 <configurationfile></configurationfile>
 <logging>
  <facilityname></facilityname>
  <logfilename></logfilename>
  </logging>
 </package>
  <packages> 
 <pfsensepkgs>

Package configuration files Package manifest file for each package specifies a configuration file for each package via config_file tag. The convention is to keep this file inside the packages/config/ directory. The format is:

 <?xml version="1.0" encoding="utf-8" ?>
 <packagegui>
  <name></name>
  <version></version>
  <title></title>
  <include_file></include_file>
  <backup_file></backup_file>
  <aftersaveredirect></aftersaveredirect>
  <configpath></configpath>
  <menu>
     <name></name>
     <section></section>
     <configfile></configfile>
     <tooltiptext></tooltiptext>
     <url>/pkg_edit.php?xml=package.xml&act=edit&id=0</url>
  </menu>
  <service>
     <name></name>
     <rcfile></rcfile>
     <executable></executable>
  </service>
  <tabs>
     <tab>
        <text></text>
        <url></url>
        <active/>
     </tab>
  </tabs>
  <additional_files_needed>
     <prefix></prefix>
     <chmod></chmod>
     <item></item>
  </additional_files_needed>
  <adddeleteeditpagefields>
     <columnitem>
        <fielddescr></fielddescr>
        <fieldname></fieldname>
     </columnitem>
  </adddeleteeditpagefields>
  <fields>
     <field>
        <fielddescr></fielddescr>
        <fieldname></fieldname>
        <description></description>
        <size></size>
        <type></type>
     </field>
  </fields>
  <custom_php_global_functions>      </custom_php_global_functions>
  <custom_php_install_command>       </custom_php_install_command>
  <custom_php_deinstall_command>      </custom_php_deinstall_command>
  <custom_add_php_command>      </custom_add_php_command>
  <custom_add_php_command_late>      </custom_add_php_command_late>
  <custom_delete_php_command>      </custom_delete_php_command>
  <custom_php_resync_config_command> </custom_php_resync_config_command>
  <start_command> </start_command>
  <process_kill_command> </process_kill_command>
 </packagegui>

Binaries from FreeBSD The actual binaries are the normal FreeBSD packages for that particular program. That can be downloaded directly from FreeBSD FTP Server.

Debugging If you get the error: Unable to communicate to my_server.com. Please check DNS, default gateway this means either (1) that your WAN is not working or (2) your pkg_config.xml is badly formed or (3) that the rpcxml server is not setup correctly.

Try using http://your_server.com/pfSense/pkg_tester.php and if you get Fatal error: Call to a member function kindOf() on a non-object in /.../.../pfSense/xmlrpc_client.inc on line 1856 then you need to comment out line 394 in xmlrpc_server.inc

It's the line that reads: header($this->server_headers); ref billm.

This article is part of the DEVELOPMENT series. Any features, steps, or general information contained in this article is 100% unsupported and may break your system. Use at your own risk!