INSTALL

CLICK INSTALLATION INSTRUCTIONS
===============================

    To compile any version of Click, you will need the GNU C compiler;
a recent version of the GNU C++ compiler; and GNU Make. The
'./configure' script should complain if it cannot find software it
needs.

    The user-level version of Click should compile and run on any
Unixlike system, including Mac OS X. The pcap library may be necessary
to communicate with the network. See the PORTABILITY section for
portability notes for architectures other than the x86.

    Click also can run inside a Linux kernel as a module. For recent
kernel versions (2.6.24-3.5 and possibly later), Click can run inside
an unmodified kernel. For older kernels, and/or for the polling
drivers that provide the best performance, you will need to patch the
kernel. See PATCHED LINUX KERNEL below.

    The preliminary FreeBSD Click kernel module compiles against
unpatched FreeBSD-STABLE versions after 700000.

    The ns-3 network simulator supports integration with Click. See
NS-3 CLICK INTEGRATION below.

    The ns-2 module requires a patched version of the NS simulator.
See the NS-2 MODULE section below.


CONFIGURING
-----------

Change to the Click source directory and run

	./configure [--prefix=PREFIX]

This will test your system and decide the versions that will work for
you (user-level, Linux kernel module, or both). It will tell you what
is wrong if it cannot compile a version. Run

	./configure --help

to see more options for './configure'.

   Notes: You can also build Click in a different directory than the source
          directory. Just change into the build directory and run
          'PATH_TO_SRCDIR/configure'.

          If the distribution does not contain a 'configure' script, you
          probably checked it out from CVS. Change into the source
          directory and run 'autoconf', then continue as above.

After running './configure', the 'make install' command will install the
user-level executable 'click', the kernel module 'click.o', configuration
optimizers like 'click-xform' and other tools, and manual pages for the
Click language, the kernel module, and many of the element classes, all
under PREFIX (which defaults to /usr/local).


USERLEVEL
---------

Build the user-level Click program in the 'userlevel' directory:

	cd CLICKDIR/userlevel
	gmake

This will eventually create an executable named 'click'. Test it by
passing it the file name of a Click-language router description
(see doc/click.5); for example,

	./click ../conf/test.click

The 'conf' directory in this distribution has a few sample configuration
files.

The configure script may not be able to find your pcap library if it's in a
nonstandard place. It will report an error in this case. To fix the error,
set the 'PCAP_INCLUDES' and 'PCAP_LIBS' variables in the options to
`./configure`. 'PCAP_INCLUDES' tells the C preprocessor where to find
'pcap.h', and 'PCAP_LIBS' tells the linker where to find 'libpcap.a'. One
example setting would be `./configure
PCAP_INCLUDES=-I/usr/local/include/pcap PCAP_LIBS=-L/usr/local/lib/pcap`.


LINUX KERNEL MODULE
-------------------

The `./configure` script will attempt to compile a Linux kernel module
by default. It will warn you if it cannot build a kernel module, and
provide some hints about how to proceed. You can also run `./configure
--enable-linuxmodule`.

To build and install the module, run

    gmake install

This will create two module object files, `linuxmodule/click.ko` and
`linuxmodule/proclikefs.ko`, and place them in `CLICKPREFIX/lib`. To
install these modules and a router configuration, run

    CLICKPREFIX/sbin/click-install ROUTERCONFIGFILE

Alternatively you could use /sbin/insmod by hand; see click.o(8).

The Linux kernel module is known to run (but not necessarily route
packets) in kernel versions 2.6.24, 2.6.32, 3.0, 3.2, and 3.5. It
should run on intermediate versions as well.


PATCHED LINUX KERNEL
--------------------

Older versions of Linux require explicit patching for Click to build.
The Click patch also adds support for true device polling, a far more
efficient way to process packets. The following instructions assume
you have at least passing familiarity with compiling and running Linux
kernels.

**NOTE:** Most Click users should either run Click at user level or
use the patchless install procedure above.

1. Archive a complete, working Linux kernel and any corresponding modules.
   This is in case something goes wrong and you need to revert to an old
   kernel.

2. Choose a kernel version for which we offer a patch. The patches are
   in the `etc` directory (e.g., `etc/linux-2.6.24.7-patch`). A given
   patch will often work for slightly different kernel versions.

3. Get the corresponding Linux kernel source distribution from
   www.kernel.org or one of its mirrors. (Patched kernels, such as Red
   Hat kernels, usually do not work.) Unpack this distribution.

4. Install the Click Linux kernel patch:

    cd LINUXSRCDIR
    patch -p0 -b < CLICKDIR/etc/linux-VERSION-patch

   The patch fixes syntax errors in several header files (the C++
   compiler doesn't accept them), adds several new functions, and
   changes the `struct device` kernel data structure. Therefore, you
   WILL need to recompile any kernel modules that touch `struct
   device`.

5. If your archived, working kernel has the same version number as the
   patched kernel, then it is a good idea to change the patched
   kernel's `EXTRAVERSION`. This way, the modules for the new kernel
   won't overwrite the old, working modules. Edit LINUXSRCDIR/Makefile
   and change the line `EXTRAVERSION =` to `EXTRAVERSION = -click`, or
   whatever you would like.

6. Configure the new kernel. The Click patch does not add any
   configuration options, so you can start from your old
   configuration, or you can do the usual 'make menuconfig'. Use a
   minimal set of options.

   Click may not be safe for kernels with involuntary preemption;
   consider turning off CONFIG_PREEMPT. CONFIG_PREEMPT_VOLUNTARY is
   OK. We welcome patches to improve Click's preemption behavior.

7. Compile and install the kernel:

    make dep
    make bzImage			(or zImage)
    make install
    make modules
    make modules_install

    You may get errors in one of these steps, such as the `make
    bzImage` step. This indicates that you turned on too many options
    when configuring your kernel. Return to Step 5, turn off the
    option that seems to be causing a problem, and try again.

8. Reboot your machine with the new kernel.

9. Now you are ready to compile and install the Click module. Rerun
   `./configure` to tell the system about your new kernel:

    ./configure [OPTIONS]

   (You may need the `--with-linux=LINUXDIR` and/or
   `--with-linux-map=SYSTEM_MAP` options.) Then build and install as above.


NS-3 CLICK INTEGRATION
----------------------

The Network Simulator 3 (NS-3) project offers support for Click integration.

The first step is to build Click. At the top of your Click source
directory, execute the following:

	./configure --enable-userlevel --disable-linuxmodule --enable-nsclick
	make

Note: The 'make install' step is optional.

Once Click has been built successfully, change into the ns-3 directory and
configure ns-3 with Click Integration support:

	./waf configure --enable-examples --with-nsclick=/path/to/click/source
	./waf build

If it says "enabled" beside "NS-3 Click Integration Support", then you’re
good to go.  The --with-nsclick argument may also point to the Click
installation prefix in case you've done a 'make install'.

Next, try running one of the examples:

	./waf --run nsclick-simple-lan

Using tcpdump or wireshark, you may then view the resulting .pcap traces
which will appear as nsclick-simple-lan-0-0.pcap and
nsclick-simple-lan-0-1.pcap.

Further information about ns-3-click is available in the ns-3 manual:
http://www.nsnam.org/docs/models/html/click.html


NS-2 MODULE
-----------

Support for integrating Click with the NS-2 simulator was originally
developed by Michael Neufeld at the University of Colorado.

To compile a Click-enabled version of the NS-2 simulator, you must first
configure and install Click with NS support.  Change to the Click source
directory and run

	./configure --prefix=CLICKPREFIX [other options] --enable-nsclick
	make install

Now, prepare to compile the NS-2 simulator.  This may involve first compiling
and installing several external packages, such as tclcl and otcl.  Then
unpack the latest version of NS; we provide patches for versions 2.30 and
2.34, but a patch may apply to later versions.  Apply the appropriate patch
from Click's etc/ directory, like so:

	cd ns-VERSION
	patch -p1 < CLICKDIR/etc/ns-VERSION-patch

Now configure NS-2, supplying the prefix you installed for Click.

	./configure [--prefix=PREFIX] --with-click=CLICKPREFIX

Compile and install NS-2.  To test nsclick, run the ns-2 simulator on one of
the sample scripts we provide:

	cd ns-VERSION/tcl/ex
	ns nsclick-simple-lan.tcl

If you get a shared library error when running ns, make sure that the
LD_LIBRARY_PATH environment variable includes the CLICKDIR/lib directory.
You should see some NS printouts intermixed with some Click printouts,
which begin with "tokernel", "discard", "fromkernel", and so forth.

Please note that the NS-2 patch no longer requires libnet.

CLICKOS
-------

Support for running Click as an operating system was originally
developed by Joao Martins, Filipe Manco, Mohamed Ahmed and Felipe Huici at
NEC Laboratories Europe.

To compile a ClickOS image you must first build all its' dependencies. For
convenience we bundle these in a repository called toolchain. The
toolchain contains 'newlib' and 'lwip' that 'mini-os' requires in
order to build:

	git clone https://github.com/sysml/mini-os.git mini-os
	git clone https://github.com/sysml/toolchain.git toolchain
	cd toolchain
	make

Note that *you can skip* this step if you wish to use your own lwip and
newlib versions for mini-os. Next, we proceed with building Click. We
require Xen headers to build the guest, and the previously built toolchain.
The latter is expected to be in the parent folder of the Click software package:

	./configure --enable-minios --with-xen=/path/to/xen/sources

If you wish to use your own, you simply have it specified in 'configure'
like the example below:

	./configure --enable-minios --with-xen=/path/to/xen/sources \
		--with-newlib=/path/to/newlib --with-lwip=/path/to/lwip

Afterwards we build the image by typing:

	make minios

And you should have an image available at './minios/build/clickos_x86_64'.

To control a ClickOS instance, i.e. instal, start, stop and remove routers and
access their element handlers, you need to build the ClickOS Control tool:

	git clone https://github.com/sysml/clickos-ctl.git clickos-ctl
	cd clickos-ctl
	make

To boot your image, type the following command in Domain-0:

	xl create minios/config.xen

Finally to install and start a click configuration do:

	clickos install -s click0 config.click

You should be able to see the following console output:

	xl console click0
	(...)
	[on_status:205] router id 0
	[on_status:206] status change to Running
	Thread "click": pointer: 0x2000c10a00, stack: 0x220000
	************************ NETFRONT for device/vif/0 **********


	net TX ring size 256
	net RX ring size 256
	backend at /local/domain/0/backend/vif/6/0
	mac is 00:15:17:15:5d:74
	**************************
	[router_thread:157] Starting driver...

ClickOS is really fast at booting up, although it mostly depends on the tools
underneath. If you are looking towards faster ways of booting up these virtual
machines, have a look at the following Xen toolstack:

	https://github.com/sysml/chaos


CLICKY GUI
----------

    To install the Clicky GUI, start by installing Click itself.  Then make
sure your system has the necessary libraries and packages installed.  On a
Debian or Ubuntu system, this will include automake, autoconf, libtool,
libgtk2.0-dev (or libgtk2-dev), and graphviz.  Then:

	cd apps/clicky
	autoreconf -i
	./configure [--prefix=PREFIX] --with-click=CLICKPREFIX
	make install


PORTABILITY
-----------

    To run a Click configuration on a non-x86 machine, you will need to
worry about alignment. By default, Click configurations assume that
unaligned accesses are OK (for instance, that it is OK to load a word from
an address that isn't start on a four-byte boundary). On most
architectures, however, unaligned accesses cause problems. To run Click on
such an architecture, you'll need to run your configurations through the
'click-align' tool before installing them. 'Click-align' (see
doc/click-align.1) figures out what alignment is required and adds elements
as necessary to make that alignment happen. It also adds an 'AlignmentInfo'
element to tell every element what kind of alignment it can expect.