Building the Code
For a development build, we recommend starting from an Untangle ISO install and converting it into a developer box.
- insert the CD and reboot to install Untangle; this will wipe out any operating system previously installed.
- when the system reboots, use the setup wizard to configure the box for your network.
- click on the 'terminal' button to get access to a shell: you will be asked for a new root password the first time you access the shell.
- alternatively, you can enable ssh
- Disable the production untangle-vm:
$ /etc/init.d./untangle-vm stop $ rm -f /etc/init.d/untangle-vm
- reconfigure debconf, and select 'Dialog' as the interface and keep other settings as the default:
$ dpkg-reconfigure debconf
- install the 'untangle-development-build' package:
$ apt-get update $ apt-get --yes install untangle-development-build
Getting the Source
The source is hosted on GitHub.
Getting the code
Fork both our main repositories (src and pkgs), and clone them using git. Note that the build dependencies are only guaranteed to be satisfied for the current stable branch (for instance, release-13.1 is the current official release is 13.1). Trying to build master can occasionally require additional dependencies.
Sending us your changes
Create pull requests targetting the master branch.
The Untangle build system works in two modes:
- Developer Build: installs the product locally (in the 'dist/' directory) so that it can be run directly from the development environment.
- Package Build: creates a set of Debian packages that can be installed using apt-get/dpkg.
The Developer Build
We recommend the Developer Build for those wishing to write apps and extend the system, since it allows for a shorter develop->build->test cycle time.
In this mode, the core of the system is functional, but some integration and peripheral functionality may be disabled or non-functional.
Actual building is simple: change to the directory you cloned using git, and run:
Upon successful build (this may take a while), the system should be fully built and installed in the 'dist/' directory.
You can then start the untangle-vm by running:
$ sudo ./dist/etc/init.d/untangle-vm start
You should be able to access the administrative gui at http://localhost/webui. The default login is "admin" with the password of "passwd"
The "dist/" directory has all the files in the same hierarchy as they would normally be found on your filesystem after a normal installation. To troubleshoot any potential issues, you can look at log files in 'dist/var/log/uvm', with 'uvm.log' usually being the most interesting.
The Package Build
The Package Build allows fuller integration and enables all features of the product. Some functionality may be disabled or non-functional.
Change to the directory you cloned using git, and then issue:
$ perl -pe 's/^deb/deb-src/' /etc/apt/sources.list.d/untangle.list > /etc/apt/sources.list.d/untangle-sources.list $ apt-get update $ apt-get build-dep untangle-vm $ debuild -us -uc
The resulting Debian packages will be built one level up ('..'):
$ dpkg -i ../untangle-*deb
The src/ hierarchy contains:
- buildtools/: scripts and libraries used by the build system.
- rakefile: main rakefile.
- debian/: the debian packaging information
- i18n-tools/: the i18n/translation tools
- <component-name>: directory for each app, library, or component. (uvm, libnetcap, firewall, etc)
A build results in the following artifacts:
- dist/: result of a developer build, mirrors the directory structure of an installed system.
- staging/: compiled classes and other pre-install artifacts.
- taskstamps.txt: stamp file for build targets.
You can ask for help on IRC.