Last edited by mshindo on 7 September 2009

Sphirewall Documentation

Welcome to the official documentation for Sphirewall, documentation revision 1.0

Getting Started/Installation

1.1Disclaimer
1.2Support and Commercial Use
1.3What is Sphirewall
1.4Pre-Installation Requirements
1.5Installing Sphirewall
1.6Configuration Files
1.7Starting and Running Sphirewall

The Management Interface

2.1Getting Started

4.1 SVN Guide
4.2 Contributors

1.x Getting Started/Installation

1.1 Disclaimer

Sphirewall is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published bythe Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Sphirewall is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Sphirewall. If not, see .

1.2 Support and Commercial Use

We are happy to provide as much support as possible for sphirewall users and when required may be able to provide support for commercial use. We will always endevour to provide as much help as possible.

Mailing Lists:
General Support: sphirewall-support@lists.sourceforge.net
Bugs: sphirewall-bugs@lists.sourceforge.net
Other: michael@sphinix.com

We also operate an irc channel on Freenode: irc.freenode.net/#sphirewall

1.3 What is Sphirewall

Sphirewall is an authenticating capture portal firewall for Linux, it is built apon the framework provided by libnetfilter_queue and runs independent of the kernel. Sphirewall was created by Michael Lawson-Searle, as an alternative to the proprietary authenticating firewalls that are available. It uses as little external libraries as possible and at the writing of this document is currently in the Beta stage of development.

1.4 Pre-installation Requirements

Sphirewall depends on the following libraries to be installed:

Library Description Link

libpam0g-dev Development libraries for PAM

gnuplot GNU Graphing software, not explicity required, but handy

openssl Encryption Protocol, required for secure sockets

libpam-krb5 Kerberos Pam Development Files

krb5-user Kerberos Library

krb5-config Kerberos Library

libssl-dev Openssl Development Files

libgcrypt-dev GNU Crypt Developement Files http://www.gnupg.org/download/

libldap2-dev LDAP Development Library

ldap-utils Common Ldap tools

libldap-2.4-2

uuid-dev Library for generating unique identifiers

libdnet or libdumbnet Networking API http://libdnet.sourceforge.net

libnetfilter_queue Netfilter Queue Library

libdumbnet-dev Network Lib

We have a bash script that will install all these libraries on a debian based system, click here to download it. Without a lot of these libraries, sphirewall not compile.

1.5 Installing Sphirewall

Sphirewall uses the GNU Autotools build system, featuring the commonly used configure script and make to compile. As of yet there are no precompiled packages available however we hope to feature these in the near future.

From a console run:
./configure, make, make install

If this returns without any error messages the installation was a success. In the event of error messages please return to step 6 or contact our support team for further assistance.

1.6 Configuration Files

Configuration of Sphirewall is generally handled within the application daemon, on installation a template configuration enviroment is loaded and this should be satisfactory for most users. However for the purpose of this documentation, here is a list of configuration files and the formats associated with them.

conf/config:
This file contains the general configuration for sphirewall, it is required on startup or else will fail:

Variable Values Description

admin_group_id Default == 0 Group id for the default admin group

auth_gateway_file Default == management/auth.html Html login page

auth_server_port Default == 8081 Remote ssl client server port, this is used by remote auth clients to connect and authenticate with sphirewall

config_dir Directory where the configuration files reside

debug_mode Default == 0 Debug mode, 99 is used by developers

dev_mode yes or no Yes prevents sphirewall from modifying the iptables stack

fail_script In the event of a sphirewall failure, this file will be run as a bash script

gid 6001 Group id for the sphirewall process

internal_device ethX Network interface that is internal

ip_forward yes Enable or disable ip forwarding

krb_config Kerberos configuration file

ldap_enabled yes or no Enable or disable the ldap module

manage_port 8080 Management interface web server port

pam_module sphirewall Filename of the pam module

sniffer_device Device to bind pcap to the monitor bandwidth

telnet_port 3490 Telnet and authentication redirect port

update_port 1090 Update daemon port

update_server Update server hostname or ip address

Some variables have been missed out.
All other configuration files are located in the $configDir directory and cannot be modified externally safely

1.7 Starting and Running Sphirewall

There are several console arguments for running sphirewall, but the default is simply:

sudo ./sphirewall start

Below is a table of the other arguments that can be used to run sphirewall.

Arg Example Description

start sudo ./sphirewalld start Default

dev sudo ./sphirewalld dev Run sphirewall in developer mode, this sets the debug_mode to 99 and disables sphirewall from modifying the iptables stack, also binds to the console and prevents forking

bind sudo ./sphirewall bind Binds sphirewall to the console and prevents forking

-f sudo ./sphirewalld -f conf/config start Specify a configuration file

-s sudo ./sphirewalld -s start Run in silent mode, no console output

Once you have sphirewall running, and a message similar to the one below has appeared on the console

Sphirewall Version: 0.9-1-1 running:
PID:6733
No threads:9
Effective User:0

You can begin configuring the sphirewall enviroment via the SSL Web Management Interface at https://localhost:8080

Now we move on to Part 2 of the Documentation

2.x The Management Interface

2.1 Getting Started

To view the management console, open a web browser such as Firefox and point the browser at the IP address of the server running sphirewall, https://IPADDDRESS:8080.

On most browsers this will prompt an error message or warning stating that the Encryption certificate cannot be verified. You must create an exception to use sphirewall. Please refer to your browser documentation for more details.

Once an exception has been created you will be prompted with a username and password field: The default user is admin with password admin.
REMEMBER TO CHANGE THIS.

More user documentation will appear here shortly, in the mean time feel free to email sphirewall-support@lists.sourceforge.net

4.x Other

4.1 SVN Guide

We use svn to store the codebase. Here are some basic instructions on its use.
Address: https://sphirewall.svn.sourceforge.net/svnroot/sphirewall
Web Access: https://sphirewall.svn.sourceforge.net

Downloading:
To download the latest code base, open up a console:

sh> svn checkout https://sphirewall.svn.sourceforge.net/svnroot/sphirewall

You should now see a list of files that are being downloaded to your computer.

Updating:
To update your version of the code (this is very important as many changes are made each day)

sh> svn update

Comiting code:
This is something only developers have access to do. Before commiting you need to ensure your code compiles on the latest revision and you have debugged. If you have added or removed file you must notify svn:

Add a file:
sh> svn add src/my_random_file.cpp

delete a file:
sh> svn del src/file_to_delete.cpp

and finally once you have checked everything, commit:
sh> svn commit -m "COMMENT GOES HERE"

The key to using svn successfully is updating every time a new revision comes out. Sadly it would be impractical at this stage to email all the developers when we release a new revision, so please check using the svn update command as much as possible

4.2 Contributors

Core/Lead DevelopersCore/Lead Developers
Michael Lawson-Searle and John Deal

A more detailed list of the team along with contact details can be found here