Commit 994c1053 authored by Eddie Kohler's avatar Eddie Kohler

Markdown for top-level documentation.

parent 8911655b
This diff is collapsed.
......@@ -16,7 +16,8 @@ software.
(c) 2001-2009 International Computer Science Institute
(c) 2004-2011 Regents of the University of California
(c) 2006-2013 Meraki, Inc.
(c) 2011-2013 President and Fellows of Harvard College
(c) 2011-2017 President and Fellows of Harvard College
(c) 1999-2017 Eddie Kohler
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
......
THE CLICK MODULAR ROUTER
========================
This is the README file for the source release for the Click modular
software router. More recent information may be available on the Web at
http://www.read.cs.ucla.edu/click/
Click is a modular router toolkit. To use it you'll need to know how to
compile and install the software, how to write router configurations, and
how to write new elements. Our ACM Transactions on Computer Systems paper,
available from the Web site, will give you a feeling for what Click can
do. Using the optimization tools under CLICKDIR/tools, you can get even
better performance than that paper describes.
CONTENTS
--------
CLICKDIR this directory
CLICKDIR/apps Click-related applications
CLICKDIR/apps/clicky ... GTK program for displaying configurations
and interacting with drivers
CLICKDIR/apps/ClickController ... Java program for interacting with drivers
CLICKDIR/bsdmodule FreeBSD 4.5 kernel module driver [NOT WORKING]
CLICKDIR/conf configuration files
CLICKDIR/doc documentation
CLICKDIR/drivers polling device drivers
CLICKDIR/elements element source code
CLICKDIR/elements/analysis ... for trace analysis and manipulation
CLICKDIR/elements/app ... for application-level protocol elements
CLICKDIR/elements/aqm ... for active queue management (RED, etc.)
CLICKDIR/elements/bsdmodule ... for FreeBSD kernel-specific elements
CLICKDIR/elements/ethernet ... for Ethernet elements
CLICKDIR/elements/etherswitch ... for Ethernet-switch elements
CLICKDIR/elements/grid ... for Grid elements (experimental)
CLICKDIR/elements/icmp ... for ICMP elements
CLICKDIR/elements/ip ... for IP, ICMP, and TCP/UDP elements
CLICKDIR/elements/ip6 ... for IPv6 elements
CLICKDIR/elements/ipsec ... for IPsec elements
CLICKDIR/elements/linuxmodule ... for Linux kernel-specific elements
CLICKDIR/elements/local ... for your own elements (empty)
CLICKDIR/elements/ns ... for 'ns'-specific elements
CLICKDIR/elements/radio ... for communicating with wireless radios
CLICKDIR/elements/standard ... for generic elements
CLICKDIR/elements/tcpudp ... for TCP and UDP elements
CLICKDIR/elements/test ... for regression test elements
CLICKDIR/elements/threads ... for thread management elements
CLICKDIR/elements/userlevel ... for user-level-specific elements
CLICKDIR/elements/wifi ... for 802.11-specific 'WiFi' elements
CLICKDIR/etc Linux and NS patches and other files
CLICKDIR/etc/samplepackage sample source code for Click element package
CLICKDIR/etc/samplellrpc sample source code for reading Click LLRPCs
CLICKDIR/etc/diagrams files for drawing Click diagrams
CLICKDIR/etc/libclick files for standalone user-level Click library
CLICKDIR/include/click common header files
CLICKDIR/include/clicknet header files defining network headers
CLICKDIR/lib common non-element source code
CLICKDIR/linuxmodule Linux kernel module driver
CLICKDIR/ns 'ns' driver (integrates with the ns simulator)
CLICKDIR/test regression tests
CLICKDIR/tools Click tools
CLICKDIR/tools/lib ... common code for tools
CLICKDIR/tools/click-align ... handles alignment for non-x86 machines
CLICKDIR/tools/click-combine ... merges routers into combined configuration
CLICKDIR/tools/click-devirtualize ... removes virtual functions from source
CLICKDIR/tools/click-fastclassifier ... specializes Classifiers into C++ code
CLICKDIR/tools/click-mkmindriver ... build environments for minimal drivers
CLICKDIR/tools/click-install ... installs configuration into kernel module
CLICKDIR/tools/click-pretty ... pretty-prints Click configuration as HTML
CLICKDIR/tools/click-undead ... removes dead code from configurations
CLICKDIR/tools/click-xform ... pattern-based configuration optimizer
CLICKDIR/tools/click2xml ... convert Click language <-> XML
CLICKDIR/userlevel user-level 'click' driver
DOCUMENTATION
-------------
The 'INSTALL' file in this directory contains installation
instructions. User documentation is in the 'doc' subdirectory. This
directory contains manual pages for the Click language, the Linux kernel
module, and several tools; it also has a script that generates manual pages
for many of the elements distributed in this package. To install these
manual pages so you can read them, follow the 'INSTALL' instructions, but
'make install-man' instead of 'make install'.
RUNNING A CLICK ROUTER
----------------------
Before playing with a Click router, you should get familiar with the
Click configuration language. You use this to tell Click how to process
packets. The language describes a graph of "elements", or packet processing
modules. See the 'doc/click.5' manual page for a detailed description, or
check the 'conf' directory 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
directly interacts with device drivers, while the user-level driver uses
packet sockets (on Linux) or the pcap library (everywhere else).
User-Level Program
..................
Run the user-level program by giving it the name of a configuration
file: 'click CONFIGFILE'.
Linux Kernel Module
...................
See the 'doc/click.o.8' manual page for a detailed description. To
summarize, install a configuration by running 'click-install CONFIGFILE'.
This will also install the kernel module if necessary and report any errors
to standard error. (You must run 'make install' before 'click-install' will
work.)
NS-3 Simulator
..............
See 'INSTALL' for more information on how to enable the NS-3 Click
Integration. Further information on ns-3-click is available in the ns-3
manual: http://www.nsnam.org/docs/models/html/click.html
NS-2 Simulator
..............
See 'INSTALL' for more information. Once a Click-enabled version of NS-2
is installed, the 'ns' command is able to run Click scripts as part of a
normal NS-2 simulation.
DPDK
....
Before running in DPDK mode, the DPDK must be set up properly as per the
DPDK documentation. That is, mainly setting 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_hugepages
mkdir -p /mnt/huge
mount -t hugetlbfs nodev /mnt/huge
On x86_64 you might achieve better performances with 1G huge pages, which
must be enabled through the kernel cmdline.
To bind eth0 to DPDK:
modprobe uio_pci_generic
dpdk/tools/dpdk_nic_bind.py --bind=uio_pci_generic eth0
Refer to the DPDK documentation for more details about huge pages and
binding devices or use the DPDK helper located in dpdk/tools/setup.sh.
Unlike most other DPDK applications, you have to pass DPDK EAL arguments
between --dpdk and "--", then pass Click arguments. As the DPDK EAL will handle
thread management instead of Click, Click's `-j` (or `--threads`) argument
will be disabled when --dpdk is provided. You should give at least the
following two EAL arguments for best practice and is required with older
versions 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 not provided, DPDK will use all available cores.
A sample command to run a click configuration on 4 cores on a computer with
4 memory 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 mode
without involving DPDK EAL, meaning that any DPDK element will not work.
Configurations
..............
A few configurations are included in the 'conf' directory, including a
Perl script that generated the IP router configurations used in our TOCS
paper ('conf/make-ip-conf.pl') and a set of patterns for the Click pattern
optimizer, click-xform ('conf/ip.clickpat'). Please check back to our Web
site for more up-to-date configurations.
ADDING YOUR OWN ELEMENTS
------------------------
Please see the FAQ in this directory to learn how to add elements to
Click.
COPYRIGHT AND LICENSE
---------------------
Most of Click is distributed under the Click license, a version of
the MIT License. See the 'LICENSE' file for details. Each source file
should identify its license. Source files that do not identify a
specific license are covered by the Click license.
Parts of Click are distributed under different licenses. The
specific licenses are listed below.
drivers/e1000*, etc/linux-*-patch, linuxmodule/proclikefs.c: These
portions of the Click software are derived from the Linux kernel, and
are thus distributed under the GNU General Public License, version 2.
The GNU General Public License is available via the Web at
<http://www.gnu.org/licenses/gpl.html>, or in the COPYING file in this
directory.
include/click/bigint.hh: This portion of the Click software
derives from the GNU Multiple Precision Arithmetic Library, and is
thus distributed under the GNU Lesser General Public License, version
3. This license is available via the Web at
<http://www.gnu.org/licenses/lgpl.html>. The LGPL specifically permits
direct linking with code with other licenses.
Element code that uses only Click's interfaces will *not* be
derived from the Linux kernel. (For instance, those interfaces have
multiple implementations, including some that run at user level.)
Thus, for element code that uses only Click's interfaces, the BSD-like
Click license applies, not the GPL or the LGPL.
BUGS, QUESTIONS, ETC.
---------------------
We welcome bug reports, questions, comments, code, whatever you'd
like to give us. We also have a mailing list for software
announcements. Write us at
click@librelist.com
- The Click maintainers:
Eddie Kohler
and others
The Click Modular Router
========================
Click is a modular router toolkit. To use it you'll need to know how to
compile and install the software, how to write router configurations, and how
to write new elements. Our [ACM Transactions on Computer Systems paper](http://dl.acm.org/citation.cfm?id=354874)
will give you a feeling for what Click can do. Using the optimization tools
under `CLICKDIR/tools`, you can get even better performance than that paper
describes.
Contents
--------
Subdirectory | Description
----------------------------- | -------------------------------
`CLICKDIR/apps` | Click-related applications
`CLICKDIR/apps/clicky` | GTK+ program for displaying configurations and interacting with drivers
`CLICKDIR/apps/csclient` | Command-line program for interacting with drivers
`CLICKDIR/apps/ClickController` | Java program for interacting with drivers
`CLICKDIR/conf` | example configuration files
`CLICKDIR/doc` | documentation
`CLICKDIR/elements` | element source code
`CLICKDIR/elements/analysis` | …for trace analysis and manipulation
`CLICKDIR/elements/app` | …for application-level protocols (e.g. FTP)
`CLICKDIR/elements/aqm` | …for active queue management (e.g. RED)
`CLICKDIR/elements/ethernet` | …for Ethernet
`CLICKDIR/elements/etherswitch` | …for an Ethernet switch
`CLICKDIR/elements/grid` | …for the Grid mobile ad-hoc wireless network protocols
`CLICKDIR/elements/icmp` | …for ICMP
`CLICKDIR/elements/ip` | …for IPv4
`CLICKDIR/elements/ip6` | …for IPv6
`CLICKDIR/elements/ipsec` | …for IPsec
`CLICKDIR/elements/linuxmodule` | …for the Linux kernel driver
`CLICKDIR/elements/local` | …for your own elements (empty)
`CLICKDIR/elements/ns` | …for the NS network simulator driver
`CLICKDIR/elements/radio` | …for communicating with wireless radios
`CLICKDIR/elements/standard` | …for simple protocol-generic elements
`CLICKDIR/elements/tcpudp` | …for TCP and UDP
`CLICKDIR/elements/test` | …for regression tests
`CLICKDIR/elements/threads` | …for thread management
`CLICKDIR/elements/userlevel` | …for the user-level driver
`CLICKDIR/elements/wifi` | …for 802.11
`CLICKDIR/etc/samplepackage` | sample source code for Click element package
`CLICKDIR/etc/samplellrpc` | sample source code for reading Click LLRPCs
`CLICKDIR/etc/diagrams` | files for drawing Click diagrams
`CLICKDIR/etc/libclick` | files for standalone user-level Click library
`CLICKDIR/include/click` | common header files
`CLICKDIR/include/clicknet` | header files defining network headers
`CLICKDIR/lib` | common non-element source code
`CLICKDIR/linuxmodule` | Linux kernel module driver
`CLICKDIR/ns` | NS driver (integrates with the NS simulator)
`CLICKDIR/test` | regression tests
`CLICKDIR/tools` | Click tools
`CLICKDIR/tools/lib` | …common code for tools
`CLICKDIR/tools/click-align` | …enforces alignment for non-x86 machines
`CLICKDIR/tools/click-combine` | …merges routers into combined configuration
`CLICKDIR/tools/click-devirtualize` | …removes virtual functions from source
`CLICKDIR/tools/click-fastclassifier` | …specializes Classifiers into C++ code
`CLICKDIR/tools/click-mkmindriver` | …build environments for minimal drivers
`CLICKDIR/tools/click-install` | …installs configuration into kernel module
`CLICKDIR/tools/click-pretty` | …pretty-prints Click configuration as HTML
`CLICKDIR/tools/click-undead` | …removes dead code from configurations
`CLICKDIR/tools/click-xform` | …pattern-based configuration optimizer
`CLICKDIR/tools/click2xml` | …convert Click language <-> XML
`CLICKDIR/userlevel` | user-level driver
Documentation
-------------
The `INSTALL` file in this directory contains installation instructions. User
documentation is in the `doc` subdirectory, which contains manual pages for
the Click language, the Linux kernel module, and several tools; it also has a
script that generates manual pages for many of the elements distributed in
this package. To install these manual pages so you can read them, follow the
`INSTALL` instructions, but `make install-man` instead of `make install`.
Running a Click Router
----------------------
Before playing with a Click router, you should get familiar with the Click
configuration language. You use this to tell Click how to process packets. The
language describes a graph of “elements,” or packet processing modules. See
the `doc/click.5` manual page for a detailed description, or check the `conf`
directory 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 directly
interacts with device drivers, while the user-level driver uses packet sockets
(on Linux) or the pcap library (everywhere else).
### User-Level Program
Run the user-level program by giving it the name of a configuration file:
`click CONFIGFILE`.
### Linux Kernel Module
See the `doc/click.o.8` manual page for a detailed description. To summarize,
install a configuration by running `click-install CONFIGFILE`. This will also
install the kernel module if necessary and report any errors to standard
error. (You must run `make install` before `click-install` will work.)
### NS-3 Simulator
See `INSTALL` for more information. Further information on NS-3 and Click is
available in [the NS-3 manual](http://www.nsnam.org/docs/models/html/click.html).
### NS-2 Simulator
See `INSTALL` for more information. Once a Click-enabled version of NS-2 is
installed, the 'ns' command is able to run Click scripts as part of a normal
NS-2 simulation.
### DPDK
Click’s user-level driver supports DPDK. Before running in DPDK mode, the DPDK
must be set up properly as per the DPDK documentation. This mainly involves
setting 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_hugepages
mkdir -p /mnt/huge
mount -t hugetlbfs nodev /mnt/huge
On x86_64 you might achieve better performances with 1G huge pages, which must
be enabled through the kernel cmdline.
To bind eth0 to DPDK:
modprobe uio_pci_generic
dpdk/tools/dpdk_nic_bind.py --bind=uio_pci_generic eth0
Refer to the DPDK documentation for more details about huge pages and binding
devices, or use the DPDK helper located in `dpdk/tools/setup.sh`.
Unlike most other DPDK applications, you have to pass DPDK EAL arguments
between `--dpdk` and `--`, then pass Click arguments. As the DPDK EAL will
handle thread management instead of Click, Click's `-j`/`--threads` argument
will be disabled when `--dpdk` is active. You should give at least the
following two EAL arguments for best practice. This is required with older
versions 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 not provided, DPDK will use all available cores.
A sample command to run a click configuration on 4 cores on a computer with 4
memory 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 mode
without involving DPDK EAL, meaning that any DPDK element will not work.
### Configurations
Some sample configurations are included in the `conf` directory, including a
Perl script that generated the IP router configurations used in our TOCS paper
(`conf/make-ip-conf.pl`) and a set of patterns for the `click-xform` pattern
optimizer (`conf/ip.clickpat`).
Adding Your Own Elements
------------------------
Please see the FAQ in this directory to learn how to add elements to Click.
Copyright and License
---------------------
Most of Click is distributed under the Click license, a version of the MIT
License. See the `LICENSE` file for details. Each source file should identify
its license. Source files that do not identify a specific license are covered
by the Click license.
Parts of Click are distributed under different licenses. The specific licenses
are listed below.
* `drivers/e1000*`, `etc/linux-*-patch`, `linuxmodule/proclikefs.c`: These
portions of the Click software are derived from the Linux kernel, and are
thus distributed under the GNU General Public License, version 2. The GNU
General Public License is available [via the Web](http://www.gnu.org/licenses/gpl.html) or
in `etc/COPYING`.
* `include/click/bigint.hh`: This portion of the Click software derives from
the GNU Multiple Precision Arithmetic Library, and is thus distributed under
the GNU Lesser General Public License, version 3. This license is available
[via the Web](http://www.gnu.org/licenses/lgpl.html) or in the `etc/COPYING.lgpl`.
Element code that uses only Click’s interfaces will *not* be derived from the
Linux kernel. (For instance, those interfaces have multiple implementations,
including some that run at user level.) Thus, for element code that uses only
Click’s interfaces, the BSD-like Click license applies, not the GPL or the
LGPL.
Bugs, Questions, etc.
---------------------
We welcome bug reports, questions, comments, code, whatever you'd like to give
us. GitHub issues are the best way to stay in touch.
- The Click maintainers: [Eddie Kohler](http://www.read.seas.harvard.edu/~kohler/) and others
GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
This version of the GNU Lesser General Public License incorporates
the terms and conditions of version 3 of the GNU General Public
License, supplemented by the additional permissions listed below.
0. Additional Definitions.
As used herein, "this License" refers to version 3 of the GNU Lesser
General Public License, and the "GNU GPL" refers to version 3 of the GNU
General Public License.
"The Library" refers to a covered work governed by this License,
other than an Application or a Combined Work as defined below.
An "Application" is any work that makes use of an interface provided
by the Library, but which is not otherwise based on the Library.
Defining a subclass of a class defined by the Library is deemed a mode
of using an interface provided by the Library.
A "Combined Work" is a work produced by combining or linking an
Application with the Library. The particular version of the Library
with which the Combined Work was made is also called the "Linked
Version".
The "Minimal Corresponding Source" for a Combined Work means the
Corresponding Source for the Combined Work, excluding any source code
for portions of the Combined Work that, considered in isolation, are
based on the Application, and not on the Linked Version.
The "Corresponding Application Code" for a Combined Work means the
object code and/or source code for the Application, including any data
and utility programs needed for reproducing the Combined Work from the
Application, but excluding the System Libraries of the Combined Work.
1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License
without being bound by section 3 of the GNU GPL.
2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a
facility refers to a function or data to be supplied by an Application
that uses the facility (other than as an argument passed when the
facility is invoked), then you may convey a copy of the modified
version:
a) under this License, provided that you make a good faith effort to
ensure that, in the event an Application does not supply the
function or data, the facility still operates, and performs
whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of
this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from
a header file that is part of the Library. You may convey such object
code under terms of your choice, provided that, if the incorporated
material is not limited to numerical parameters, data structure
layouts and accessors, or small macros, inline functions and templates
(ten or fewer lines in length), you do both of the following:
a) Give prominent notice with each copy of the object code that the
Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license
document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that,
taken together, effectively do not restrict modification of the
portions of the Library contained in the Combined Work and reverse
engineering for debugging such modifications, if you also do each of
the following:
a) Give prominent notice with each copy of the Combined Work that
the Library is used in it and that the Library and its use are
covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license
document.
c) For a Combined Work that displays copyright notices during
execution, include the copyright notice for the Library among
these notices, as well as a reference directing the user to the
copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this
License, and the Corresponding Application Code in a form
suitable for, and under terms that permit, the user to
recombine or relink the Application with a modified version of
the Linked Version to produce a modified Combined Work, in the
manner specified by section 6 of the GNU GPL for conveying
Corresponding Source.
1) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (a) uses at run time
a copy of the Library already present on the user's computer
system, and (b) will operate properly with a modified version
of the Library that is interface-compatible with the Linked
Version.
e) Provide Installation Information, but only if you would otherwise
be required to provide such information under section 6 of the
GNU GPL, and only to the extent that such information is
necessary to install and execute a modified version of the
Combined Work produced by recombining or relinking the
Application with a modified version of the Linked Version. (If
you use option 4d0, the Installation Information must accompany
the Minimal Corresponding Source and Corresponding Application
Code. If you use option 4d1, you must provide the Installation
Information in the manner specified by section 6 of the GNU GPL
for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the
Library side by side in a single library together with other library
facilities that are not Applications and are not covered by this
License, and convey such a combined library under terms of your
choice, if you do both of the following:
a) Accompany the combined library with a copy of the same work based
on the Library, uncombined with any other library facilities,
conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it
is a work based on the Library, and explaining where to find the
accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions
of the GNU Lesser General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the
Library as you received it specifies that a certain numbered version
of the GNU Lesser General Public License "or any later version"
applies to it, you have the option of following the terms and
conditions either of that published version or of any later version
published by the Free Software Foundation. If the Library as you
received it does not specify a version number of the GNU Lesser
General Public License, you may choose any version of the GNU Lesser
General Public License ever published by the Free Software Foundation.
If the Library as you received it specifies that a proxy can decide
whether future versions of the GNU Lesser General Public License shall
apply, that proxy's public statement of acceptance of any version is
permanent authorization for you to choose that version for the
Library.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment