Skip to content

Latest commit

 

History

History
342 lines (239 loc) · 12.5 KB

INSTALL.md

File metadata and controls

342 lines (239 loc) · 12.5 KB
Raw

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 “Portability,” below, for portability notes for architectures other than the x86.

Click also can run inside an unmodified Linux kernel as a module. For very old kernels, and/or for polling network drivers (not recommended), you may need to patch the kernel.

The NS-3 network simulator supports integration with Click. The NS-2 simulator also supports integration, but a patched NS is required.

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.

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, 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.ko, 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).

User-level driver

The user-level driver is an executable named click. It is built in the userlevel/ subdirectory. Test it by passing it the file name of a Click-language router description (see doc/click.5); for example,

./userlevel/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 driver

The Linux kernel driver is a kernel module named click.ko. It is built in the linuxmodule/ subdirectory, along with a helper module called proclikefs.ko. To install the kernel module and a router configuration, run make install, then

click-install ROUTERCONFIGFILE

Give ./configure the --enable-linuxmodule argument if you definitely want to build a kernel module. If the configure process can’t build a module, it will provide some hints about how to proceed.

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 (deprecated)

Older versions of Linux require explicit patching for Click to build. The Click patch also adds support for true device polling, an 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 https://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 install make modules make modules_install

    Errors in one of these steps usually 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 Simulator Driver

The Network Simulator 3 (NS-3) project offers support for Click integration. The first step is to build Click. Execute the following in your Click source directory:

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

Due to limitations of the NS-3 build procedure, you must configure Click in its source directory.

Once Click has built, change into the ns-3 directory and configure NS-3 with Click integration support:

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

If it says NS-3 Click Integration : enabled, then you’re good to go.

Next, build, and try running one of the examples:

./waf build
./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.

NS-2 Simulator Driver

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 cnplab/toolchain. The toolchain contains newlib and lwip that mini-os requires in order to build:

git clone https://github.com/cnplab/mini-os.git mini-os
git clone https://github.com/cnplab/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 boot your image, type the following command in Domain-0:

xl create minios/config.xen

Finally to instantiate a Click configuration, you need to fetch your guest virtual machine id and dump your router configuration through the xenstore service:

DOMID=`xl list | grep click0 | awk -F' ' '{ print $2 }'`
xenstore-write /local/domain/$DOMID/clickos/0/config/0 "`cat config.click`"
xenstore-write /local/domain/$DOMID/clickos/0/status "Running"

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 cnplab/cosmos toolstack.

DPDK

Support for using DPDK for high-speed userspace I/O is enabled using

./configure RTE_SDK=... RTE_TARGET=... \
    --enable-dpdk --enable-user-multithread --disable-linuxmodule

where RTE_SDK and RTE_TARGET are defined as per the DPDK documentation, e.g.

RTE_SDK=/path/to/dpdk-2.1.0/
RTE_TARGET=x86_64-native-linuxapp-gcc

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.