pgl/INSTALL                                    Wed, 20 Jun 2012 22:57:43 +0200


Table of Contents:
==================

1.) Manual installation
2.) Uninstall
3.) Build dependencies and runtime environment
4.) Available packages, build scripts and other distribution specific tips




1.) Manual installation
=======================

This is the general method to install pgl. Please also have a look at the
distribution specific section (chapter 4).


Step 1: Get the source:
-----------------------

Either get the latest stable release from peerguardian.sourceforge.net and
unpack it.

Or get the current development code (the following is one command line!):
  git clone git://peerguardian.git.sourceforge.net/gitroot/peerguardian/peerg
  uardian


Step 2: Install pgl's dependencies
----------------------------------

Install the build dependencies (including the development headers) and runtime
environment for the components (see chapter 3).


Step 3: Compilation and installation
------------------------------------

Step 3.0: Create/update autotools files (only required for git version)
-----------------------------------------------------------------------

If you are using the development version from the git repository generate
the autotools files first. Go to the peerguardian/pgl directory and run:
  ./autogen.sh

To update the files run:
  autoreconf


Step 3.1: Configure
-------------------

Pgl uses autotools which comes with several configure-switches you have
to check before compiling. Go to the pgl/ directory and run:
  ./configure --help

Check the options and the paths. There are some common paths and options you
should consider to set like:
  --prefix         [default: /usr/local]
  --sysconfdir     [default: $prefix/etc, recommended: /etc]
  --localstatedir  [default: $prefix/var, recommended: /var]
  --with-iconsdir  [default: $datadir/pixmaps]
  --with-initddir  [default: $sysconfdir/init.d]
  --with-logdir    [default: $localstatedir/log/pgl]
  --with-piddir    [default: $localstatedir/run]
  --with-tmpdir    [default: /tmp]
  --with-lsb=      [default: none/built-in,
                    recommended: /lib/lsb/init-functions]

IMPORTANT: Especially the "--sysconfdir=/etc" setting is required for a working
installation! Otherwise you should expect e.g. dbus errors.

For a slick installation you can build without the GUI and turn off dbus
support:
  --without-qt4
  --disable-dbus

Especially for embedded devices (like router or NAS box) you might disable
storing of textual IP range descriptions:
  --enable-lowmem
But generally it is recommended (and required for the GUI) to use the default,
which is not to use this feature.

Now you should be clear about the settings you need for your distribution and
run something similar to:
  ./configure \
    --prefix=/my/prefix \
    --with-initddir=/my/initddir \
    --sysconfdir=/etc

Full example configure line for a complete build and full system integration
(on a Debian system):
  ./configure \
    --prefix=/usr \
    --mandir=/usr/share/man \
    --datadir=/usr/share \
    --sysconfdir=/etc \
    --localstatedir=/var \
    --with-lsb=/lib/lsb/init-functions \
    --enable-cron \
    --enable-dbus \
    --enable-logrotate \
    --enable-networkmanager \
    --enable-zlib \
    --with-qt4 \
    --disable-lowmem

Minimal example line for a complete build and full system integration (on a
Debian system). Installs most things to /usr/local
  ./configure \
    --sysconfdir=/etc \
    --localstatedir=/var \
    --with-lsb=/lib/lsb/init-functions

ArchLinux users probably have to set:
  --with-initddir=/etc/rc.d


Step 3.2: Build and install
---------------------------

After configure you can build and install the package, just issue:
  make
  make install


Step 3.3: Activate the init script
----------------------------------

On some systems (e.g. Debian and Ubuntu based) it may be required to activate
the init script manually:
  update-rc.d pgl defaults

Or alternatively:
  /usr/lib/lsb/install_initd /etc/init.d/pgl

RedHat's system initialization:
  chkconfig add pgl
  chkconfig pgl on

Or probably manually, something like:
  ln -s /etc/init.d/pgl /etc/rc0.d/K01pgl
  ln -s /etc/init.d/pgl /etc/rc1.d/K01pgl
  ln -s /etc/init.d/pgl /etc/rc2.d/S20pgl
  ln -s /etc/init.d/pgl /etc/rc3.d/S20pgl
  ln -s /etc/init.d/pgl /etc/rc4.d/S20pgl
  ln -s /etc/init.d/pgl /etc/rc5.d/S20pgl
  ln -s /etc/init.d/pgl /etc/rc6.d/K01pgl

Or something else, please tell us how it works for your distribution!

Other systems, like Gentoo, don't need this activation of the init script.




2.) Uninstall
===============================

To uninstall issue the following command:
  make uninstall




3.) Build dependencies and runtime environment
==============================================

Build dependencies:
- autotools (autoconf, automake, libtoolize)
- nfnetlink development files
- libnetfilter-queue development files
- libdbus development files (optional, required for the GUI)
- Qt4 development files including Qt4 dbus (optional, required for the GUI)
- zlib development files (optional, for loading gz compressed blocklists
  directly)

Runtime environment pgld:
- the above libraries
- iptables (required)
- netfilter kernel support (Linux kernel >= 2.6.13 for NFQUEUE support)
  Either as modules or directly built in the kernel. These are the modules that
  are loaded here. Note that "xt_" may be named "ip_" or "ipt_" on older
  systems. This list was compiled with:
    lsmod|grep -E "^x|^nf|^ip"|grep -Ev "^ip6|^ipv6"|sed "s| .*||"|sort
  iptable_filter
  ip_tables
  ipt_REJECT
  nf_conntrack
  nf_conntrack_ipv4
  nf_defrag_ipv4
  nfnetlink
  nfnetlink_queue
  x_tables
  xt_iprange
  xt_mark
  xt_multiport
  xt_NFQUEUE
  xt_state
  xt_tcpudp
- dbus daemon (optional)

 Runtime environment pglcmd:
- pgld
- wget (optional, needed for blocklists update)
- p7zip (optional, needed for blocklists packed as .7z)
- unzip (optional, needed for blocklists packed as .zip)
- start-stop-daemon (optional)
- awk, sed, grep, basename, dirname, cat, cd, mv, cp, zcat, md5sum, renice,
  pidof (those should really be on every system)
- /usr/bin/printf (optional, needed during "update" for archive type
  detection)
- /lib/lsb/init-functions (optional,there's a copy built in)
- NetworkManager (optional, needed for automatic whitelisting of newly
  brought up network interfaces. Not needed in Debian.)
- sendmail (optional, needed to send informational (blocklist updates) and
  warning mails (if pglcmd.wd detects a problem.)

 Runtime environment pglgui:
- pgld
- pglcmd
- Qt4
- dbus
- whois




4.) Available packages, build scripts and other distribution specific tips
==========================================================================

pgl was written and tested under Debian Gnu/Linux Wheezy. However it should run
under every Linux system. It is our goal to make life as easy as possible for
users and packagers.

NOTE FOR PACKAGERS:
If you are a packager just contact us at
http://sourceforge.net/projects/peerguardian/ or
jre-phoenix@users.sourceforge.net.
We'll gladly give you all possible support, change the code if feasible and
publish your work. Of course you are welcome to join the project and e.g.
commit directly to the git repository.
To test if pgl is correctly integrated in your system, you'll have to verify
the correct handling of the init, cron, NetworkManager and logrotate files
(all are part of pglcmd, logrotate also of pgld), and may test if
LSB="/lib/lsb/init-functions" works.


deb packages:
-------------
jre provides official packages in a repository for automatic updates:
Debian at http://moblock-deb.sourceforge.net
Ubuntu at https://launchpad.net/~jre-phoenix/+archive/ppa

Debian RFP: http://bugs.debian.org/578192
Ubuntu RFP: https://bugs.launchpad.net/ubuntu/+bug/109822


rpm packages [outdated]:
------------------------
CentOS by agent86 (last update 06-20-2011, pgl 2.0.4):
http://forums.phoenixlabs.org/thread-16383-post-120468.html
spec and patch file
rpms (including netfilter libraries)
RedHat's system initialization:
  chkconfig add pgl
  chkconfig pgl on

openSUSE 11.3/x64 [outdated]:
-----------------------------
by pixecs (last update 06-03-2011, pgl 2.0.4):
http://forums.phoenixlabs.org/thread-15882-post-120482.html#pid120482


ARCH / AUR (Arch User Repo):
----------------------------
PKGBUILD by Gilrain:
https://aur.archlinux.org/packages.php?ID=51839
(Last Updated: Thu, 14 Jun 2012 08:52:59 +0000 for 2.2.0)


Gentoo:
-------
available in main portage tree by our Gentoo maintainer hasufell:
http://packages.gentoo.org/package/net-firewall/pglinux


Slackware [outdated]:
---------------------
by godmachine81:
branch "pgl_slackware" in the git repository, slack tar available.


synology:
---------
2009 by dino:
http://forums.phoenixlabs.org/thread-1622-post-119717.html#pid119717
