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 Intel x86 Unix system. The pcap library may be necessary to communicate with the network. See the end of this document for portability notes for other architectures. The Linux kernel module requires a patched Linux 2.2, 2.4, or 2.6 system. We provide patches for Linux 2.2.18 through 2.2.21, 2.4.18 through 2.4.32, and 2.6.16.13. The patches do not apply against Red Hat kernels; use vanilla kernels from kernel.org. The preliminary FreeBSD Click kernel module compiles against unpatched FreeBSD-STABLE versions after 440002. The ns module requires a patched version of the NS simulator. We provide a patch for ns version 2.29. See the NS SIMULATOR section below. CONFIGURING ----------- If you plan to use the Linux kernel module, you must patch your kernel first. See the 'Linux module' section below. 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 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 your 'PCAP_INCLUDES' and 'PCAP_LIBS' environment variables and rerun './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 'PCAP_INCLUDES=-I/usr/local/include/pcap' and 'PCAP_LIBS=-L/usr/local/lib/pcap'. LINUX MODULE ------------ Before you can compile or use the Click loadable kernel module, you need to install, patch, compile, and boot a compatible Linux kernel. These instructions assume you have at least passing familiarity with compiling and running Linux kernels. 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. Get a vanilla 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 into /usr/src/linux. (Save the old kernel source tree, if you had one.) We supply patches for Linux 2.2.18-21, 2.4.18-28, and 2.6.16.13. A patch may or may not work for a slightly different kernel version; we suggest you try it. 3. Install the Click Linux kernel patch: cd /usr/src/linux patch -p0 -b < CLICKDIR/etc/linux-VERSION-patch Use the VERSION that applies to your kernel, as follows: Kernel version Patch 2.6.16.13 linux-2.6.16.13-patch 2.4.32 linux-2.4.32-patch 2.4.28 linux-2.4.26-patch 2.4.27 linux-2.4.26-patch 2.4.26 linux-2.4.26-patch 2.4.26-Debian debian-2.4.26-patch 2.4.21 linux-2.4.21-patch 2.4.20 linux-2.4.20-patch 2.4.19 linux-2.4.18-patch 2.4.18 linux-2.4.18-patch 2.2.21 linux-2.2.19-patch 2.2.20 linux-2.2.19-patch 2.2.19 linux-2.2.19-patch 2.2.18 linux-2.2.18-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'. 4. If your archived, working kernel has the same version number as the patched kernel (they're both 2.4.18, for example), 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 /usr/src/linux/Makefile and change the line 'EXTRAVERSION =' to 'EXTRAVERSION = -click', or whatever you would like. 5. 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. 6. 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. 7. Edit /etc/lilo.conf to tell it about the new kernel, then run /sbin/lilo. 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: rm -f config.cache ; ./configure [OPTIONS] If your Linux source is not in /usr/src/linux, give './configure' the '--with-linux=LINUXDIR' option. If your System.map file is not in LINUXDIR/System.map, give it the '--with-linux-map=MAPFILE' option. If './configure' reports "Your header files must be patched before a C++ program can include them", check that you applied the patch in Step 3, and that you supplied the correct '--with-linux' option to './configure'. 10. Then build and install the click module, its companion proclikefs module, and the language tools: gmake install If you get errors while compiling the Linux kernel module (the 'linuxmodule' directory), and the errors look like they are in Linux header files, you may have turned on too many options when configuring your kernel. Return to Step 5, turn off the option that seems to be causing a problem (for example, an error involving the "atalk_iface *" type means you should turn off AppleTalk via CONFIG_ATALK), and try again. 11. This will create two module object files, 'linuxmodule/click.o' and 'linuxmodule/proclikefs.o', 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). NS MODULE --------- Support for integrating Click with the NS simulator was originally developed by Michael Neufeld at the University of Colorado. To compile a Click-enabled version of the NS 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-ns make install Now, prepare to compile the NS 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 a patch for version 2.29, but the 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, supplying the prefix you installed for Click. ./configure [--prefix=PREFIX] --with-click=CLICKPREFIX Compile and install NS. To test nsclick, run the ns simulator on one of the sample scripts we provide: cd ns-VERSION/tcl/ex ns nsclick-simple-lan.tcl Please note that the NS patch no longer requires libnet. 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.