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' package:
$ apt-get update $ apt-get --yes install untangle-development-build
Getting the Source
The source is hosted on GitLab.
Planning on contributing
If you plan on submitting merge requests to us, it's recommended you open a GitLab account, clone our main repository, and check that out using git.
Getting the code
For instance if you named your clone "src-yours", you would use the following command (after having uploaded a valid public SSH key to GitLab):
$ git clone firstname.lastname@example.org:~<your-gitorious-user>/untangle.com/ngfw_src-yours.git
Sending us your changes
First, push your changes back to GitLab; roughly, it should go something like (from your working directory):
git commit -a (1) git pull --rebase git://gitlab.com/untangle.com/ngfw_src.git master (2) git push (3)
(1) is to commit locally, no svn equivalent (2) is to get your copy up-to-date (think "svn up") (3) is to push to GitLab (think "svn commit")
Then, create a merge request using the GitLab interface: click on "merge", and follow the assistant (make sure you ask for a merge to our main untangle:src repository, in the master branch); we'll get your request automatically.
You can also anonymously clone our main repository, using the following command:
$ git clone git://gitlab.com/untangle.com/ngfw_src.git
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 Nodes 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.
- <component>-name: directory for each Node, Casing, and Component.
- prj.el: Emacs JDEE Project file.
- G*: GNU Global tag files
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.