Repository files navigation

Click is a modular router toolkit. To use it you'll need to know how tocompile and install the software, how to write router configurations, and howto write new elements. OurACM Transactions on Computer Systems paperwill give you a feeling for what Click can do. Using the optimization toolsunderCLICKDIR/tools, you can get even better performance than that paperdescribes.

TheINSTALL.md file in this directory contains installation instructions. Userdocumentation is in thedoc subdirectory, which contains manual pages forthe Click language, the Linux kernel module, and several tools; it also has ascript that generates manual pages for many of the elements distributed inthis package. To install these manual pages so you can read them, follow theINSTALL.md instructions, butmake install-man instead ofmake install.

Before playing with a Click router, you should get familiar with the Clickconfiguration language. You use this to tell Click how to process packets. Thelanguage describes a graph of “elements,” or packet processing modules. Seethedoc/click.5 manual page for a detailed description, or check theconfdirectory for some simple examples.

Click can be compiled as a user-level program or as a kernel module for Linux.Either driver can receive and send packets; the kernel module directlyinteracts with device drivers, while the user-level driver uses packet sockets(on Linux) or the pcap library (everywhere else).

Run the user-level program by giving it the name of a configuration file:click CONFIGFILE.

See thedoc/click.o.8 manual page for a detailed description. To summarize,install a configuration by runningclick-install CONFIGFILE. This will alsoinstall the kernel module if necessary and report any errors to standarderror. (You must runmake install beforeclick-install will work.)

SeeINSTALL.md for more information. Further information on NS-3 and Click isavailable inthe NS-3 manual.

SeeINSTALL.md for more information. Once a Click-enabled version of NS-2 isinstalled, the 'ns' command is able to run Click scripts as part of a normalNS-2 simulation.

Click’s user-level driver supports DPDK. Before running in DPDK mode, the DPDKmust be set up properly as per the DPDK documentation. This mainly involvessetting up huge pages and binding some NIC to the DPDK userspace driver. E.g.,to set up huge pages:

echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepagesmkdir -p /mnt/hugemount -t hugetlbfs nodev /mnt/huge

On x86_64 you might achieve better performances with 1G huge pages, which mustbe enabled through the kernel cmdline.

Intel NICs use entierly userspace drivers and needs to be bound to DPDK.Eg., to bind eth0 to DPDK:

modprobe uio_pci_genericdpdk/tools/dpdk_nic_bind.py --bind=uio_pci_generic eth0

Refer to theDPDK documentation for more details about huge pages and bindingdevices.

Unlike most other DPDK applications, you have to pass DPDK EAL argumentsbetween--dpdk and--, then pass Click arguments. As the DPDK EAL willhandle thread management instead of Click, Click's-j/--threads argumentwill be disabled when--dpdk is active. You should give at least thefollowing two EAL arguments for best practice. This is required with olderversions of DPDK, even if running on a single core:

• -c COREMASK: hexadecimal bitmask of cores to run on
• -n NUM: number of memory channels

If-c or-l is not provided, DPDK will use all available cores.

A sample command to run a click configuration on 4 cores on a computer with 4memory channels and listen for control connections on TCP port 8080 would be:

click --dpdk -c 0xf -n 4 -- -p 8080 configfile

If Click is launched without--dpdk, it will run in normal userlevel modewithout involving DPDK EAL, meaning that any DPDK element will not work.

Some sample configurations are included in theconf directory, including aPerl script that generated the IP router configurations used in our TOCS paper(conf/make-ip-conf.pl) and a set of patterns for theclick-xform patternoptimizer (conf/ip.clickpat).

Please see the FAQ in this directory to learn how to add elements to Click.

Most of Click is distributed under the Click license, a version of the MITLicense. See theLICENSE file for details. Each source file should identifyits license. Source files that do not identify a specific license are coveredby the Click license.

Parts of Click are distributed under different licenses. The specific licensesare listed below.

• drivers/e1000*,etc/linux-*-patch,linuxmodule/proclikefs.c: Theseportions of the Click software are derived from the Linux kernel, and arethus distributed under the GNU General Public License, version 2. The GNUGeneral Public License is availablevia the Web andinetc/COPYING.

• include/click/bigint.hh: This portion of the Click software derives fromthe GNU Multiple Precision Arithmetic Library, and is thus distributed underthe GNU Lesser General Public License, version 3. This license is availablevia the Web and inetc/COPYING.lgpl.

Element code that uses only Click’s interfaces willnot be derived from theLinux kernel. (For instance, those interfaces have multiple implementations,including some that run at user level.) Thus, for element code that uses onlyClick’s interfaces, the BSD-like Click license applies, not the GPL or theLGPL.

We welcome bug reports, questions, comments, code, whatever you'd like to giveus. GitHub issues are the best way to stay in touch.

• The Click maintainers:Eddie Kohler and others