Creating a Custom Package Repository
These directions will walk through setting up a custom package repository, in order to host packages locally or develop/test package changes.
- 1 Step 1: Web Server
- 2 Step 2: Packages
- 3 Step 3: Test
- 4 Step 4: Have pfSense use the repository
- 5 Step 5: Check it out
- 6 Step 6: Edit Package List
- 7 Step 7: Edit Package URLs
- 8 Step 8: Patch and play
- 9 Step 9: Report bugs
- 10 Maintaining the Package Repository
- 11 Making New Packages
Step 1: Web Server
Set up a web server (which must be visible from the pfSense box), and install PHP. After installing PHP, enable it in the web server. On an Apache 2.x server, add this to httpd.conf:
AddHandler php5-script php AddType text/html php
On a Lighttpd server, enable the server module "mod_fastcgi" and add this to lighttpd.conf:
fastcgi.server = ( ".php" => ( "127.0.0.1" => ( "socket" => "/var/run/lighttpd/php-fastcgi.socket", "bin-path" => "/usr/local/bin/php-cgi", "max-procs" => 2, "bin-environment" => ( "PHP_FCGI_CHILDREN" => "16", "PHP_FCGI_MAX_REQUESTS" => "10000" ), "bin-copy-environment" => ( "PATH", "SHELL", "USER" ), "broken-scriptfilename" => "enable" ) ) )
This server can be located on a WAN, LAN, or even a VPN as long as it is reachable by the pfSense box without hitting some kind of authenticating proxy or portal.
It can't easily be done from a pfSense box, itself without custom modifications to the XML-RPC code. It should be a completely separate server.
Step 2: Packages
Next, download the package server XML-RPC code, and the package repository itself.
Install git on the server or download the repositories to a workstation and upload them with FTP.
If a UNIX-based web server is being used, go to the root of the web server (e.g. /usr/local/www/) and run the following commands:
# git clone git://github.com/pfsense/xmlrpc-server.git pfSense
This will download the XML-RPC package code into the pfSense folder (the default location looked for by pfSense installations). This path may be changed, it is governed by the xmlrpcpath setting in /etc/inc/globals.inc located on the pfSense firewall.
# git clone git://github.com/pfsense/pfsense-packages.git packages
This will download the actual packages repository, which contains the individual package GUI elements, pfSense-related package code, and associated XML files. Beware, this repository is very large, and will consume a lot of disk space. This does not contain the actual binary package archives.
For the following pfSense Versions the Web Server must be setup in the following way...
The repo needs to have a server root with 2 subdirectories and nothing else: /pfSense and /packages (both in the root of repo)
The /pfSense content must be the root and a subdirectory /packages.
If XMLRPC is still not working check the following in xmlrpc.php:
xmlrpc.php, line 45:
$path_to_files = './xmlrpc/';
xmlrpc.php, line 124:
$path_to_files = './packages/';
Cloning on a Workstation
If git and/or shell access is not available on the web server, the packages may be still be hosted. Clone those repositories on a workstation or another server first.
Use gitbash/msysgit on Windows, or git packages for any other OS. After cloning the repositories on a local system, upload the files to the proper places on the web server.
There is no need to upload the .git folders from these local repositories, but do not delete them.
To edit the package repository files as described in later steps, edit them on the workstation and then upload them after they have been changed.
Step 3: Test
Both URLs should show a PHP array if everything is working properly.
The web server may need configured so that the packages directory does not have PHP code processed underneath that directory tree. Many packages try to download .php files and if this is not done, .php files that packages attempt to download will be interpreted by the web server instead of downloaded intact.
Create a .htaccess file in the packages directory or the config directory under that, containing:
RemoveHandler .php RemoveType .php
Step 4: Have pfSense use the repository
- Go to the pfSense GUI.
- Browse to http://pfsense/pkg_mgr_settings.php
- Enter the hostname of the server, such as reposerver
- NOTE: "reposerver" is only the hostname, NOT a full URL.
Screenshot of Package Settings:
Step 5: Check it out
- Go to the GUI under System -> Packages
- The packages listed should be served by the custom repository
Step 6: Edit Package List
To limit the packages which are shown in this list, edit the file in the packages directory for the appropriate platform. For pfSense 2.0/2.1 it is pkg_config.8.xml. For pfSense 2.0/2.1 64-bit packages, this is pkg_config.8.xml.amd64. For pfSense 2.2, both are in one file: pkg_config.10.xml.
Remove the entries from the file that are not wanted, or set their required_version much higher (3, 4, etc)
Change paths for packages intended to be useed so that they point to a custom server as well. For example, on the System Patches package, the stock pkg_config.10.xml looks like this for the config_file URL:
Change that to:
And then edit packages/config/systempatches/systempatches.xml on the server for the next step.
It is usually OK to leave the FreeBSD-style package URLs the same (<blah>.pbi or .tbz) unless the custom server will mirror the entire set of binary packages as well.
Step 7: Edit Package URLs
As with above, for editing and testing of packages, edit the package's XML file and alter the paths so that they point to the same files on the custom server instead of files on pfSense servers. Check the package's .inc files if it has any, as the installation routine may also download additional files.
Step 8: Patch and play
Now patch the package configuration files, and install additional modified packages! Or leave it alone and run a simple local repository.
Step 9: Report bugs
If a change fixed a problem, open a ticket at http://redmine.pfsense.org with the patched changes so they can be fixed for everyone else.
Maintaining the Package Repository
To keep the repository up-to-date, change to the packages directory and then run:
# git pull
That will update the repository with any changes made since the initial clone. If changes were made, it may be possible to keep them if they are committed locally first:
# git commit -a -m 'My Local Changes' # git pull
Changes should be reapplied after the new code is updated, provided none of the changes conflict.
Making New Packages
To make new packages, or for more information about the format of the files, see Developing Packages
Copied (with some modifications) from http://forum.pfsense.org/index.php/topic,25519.0.html by kaarposoft