Skip to content

Commit

Permalink
Update README.md examples and INSTALL.md
Browse files Browse the repository at this point in the history 
Signed-off-by: Brenden Blanco <[email protected]>
  • Loading branch information
Brenden Blanco committed Jul 8, 2015
1 parent 80221ad commit 3151843
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 68 deletions.
60 changes: 60 additions & 0 deletions INSTALL.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Ubuntu - Docker edition

The build dependencies are captured in a [Dockerfile](Dockerfile.ubuntu), the
output of which is a .deb for easy installation.

* Start with a recent Ubuntu install (tested with 14.04 LTS)
* Install a [>= 4.2 kernel](https://kernel.ubuntu.com/~kernel-ppa/mainline/)
with headers
* Reboot
* Install [docker](https://docs.docker.com/installation/ubuntulinux/)
(`wget -qO- https://get.docker.com/ | sh`)
* Run the Dockerfile for Ubuntu - results in an installable .deb
* `git clone https://github.com/iovisor/bcc; cd bcc`
* `docker build -t bcc -f Dockerfile.ubuntu .`
* `docker run --rm -v /tmp:/mnt bcc sh -c "cp /root/bcc/build/*.deb /mnt"`
* `sudo dpkg -i /tmp/libbcc*.deb`
* Run the example
* `sudo python /usr/share/bcc/examples/hello_world.py`

# Fedora - Docker edition

The build dependencies are captured in a [Dockerfile](Dockerfile.fedora), the
output of which is a .rpm for easy installation. This version takes longer since
LLVM needs to be compiled from source.

* Start with a recent Fedora install (tested with F22)
* Install a [>= 4.2 kernel](https://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug/x86_64/)
with headers
* Reboot
* Install [docker](https://docs.docker.com/installation/fedora/)
* Run the Dockerfile for Fedora - results in an installable .rpm
* `git clone https://github.com/iovisor/bcc; cd bcc`
* `docker build -t bcc -f Dockerfile.fedora .`
* `docker run --rm -v /tmp:/mnt bcc sh -c "cp /root/bcc/build/*.rpm /mnt"`
* `sudo rpm -ivh /tmp/libbcc*.rpm`
* Run the example
* `sudo python /usr/share/bcc/examples/hello_world.py`

# Ubuntu - From source

To build the toolchain from source, one needs:
* LLVM 3.7 or newer, compiled with BPF support (default=on)
* Clang 3.7, built from the same tree as LLVM
* cmake, gcc (>=4.7), flex, bison

* Add the [LLVM binary repo](https://llvm.org/apt/) to your apt sources
* `echo "deb https://llvm.org/apt/trusty/ llvm-toolchain-trusty main" | sudo tee /etc/apt/sources.list.d/llvm.list`
* `wget -O - https://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add -`
* `sudo apt-get update`
* Install build dependencies
* `sudo apt-get -y install bison build-essential cmake flex git libedit-dev python zlib1g-dev`
* Install LLVM and Clang development libs
* `sudo apt-get -y install libllvm3.7 llvm-3.7-dev libclang-3.7-dev`
* Install and compile BCC
* `git clone https://github.com/iovisor/bcc.git`
* `mkdir bcc/build; cd bcc/build`
* `cmake .. -DCMAKE_INSTALL_PREFIX=/usr`
* `make`
* `sudo make install`

143 changes: 75 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@ This directory contains source code for BCC, a toolkit for creating small
programs that can be dynamically loaded into a Linux kernel.

The compiler relies upon eBPF (Extended Berkeley Packet Filters), which is a
feature in Linux kernels starting from 3.19. Currently, this compiler leverages
feature in Linux kernels starting from 3.15. Currently, this compiler leverages
features which are mostly available in Linux 4.1 and above.

## Installing

See [INSTALL.md](INSTALL.md) for installation steps on your platform.

## Motivation

BPF guarantees that the programs loaded into the kernel cannot crash, and
Expand Down Expand Up @@ -97,12 +101,78 @@ bcc/examples$ sudo python hello_world.py

### Networking

Walkthrough TBD, see
[Neighbor Sharing example](examples/tc_neighbor_sharing.py) for longer
example.
At RedHat Summit 2015, BCC was presented as part of a [session on BPF](https://www.devnation.org/#7784f1f7513e8542e4db519e79ff5eec).
A multi-host vxlan environment is simulated and a BPF program used to monitor
one of the physical interfaces. The BPF program keeps statistics on the inner
and outer IP addresses traversing the interface, and the userspace component
turns those statistics into a graph showing the traffic distribution at
multiple granularities. See the code [here](examples/tunnel_monitor).

[![Screenshot](https://img.youtube.com/vi/yYy3Cwce02k/0.jpg)](https://youtu.be/yYy3Cwce02k)

### Tracing

Here is a slightly more complex tracing example than Hello World. This program
will be invoked for every task change in the kernel, and record in a BPF map
the new and old pids.

The C program below introduces two new concepts.
The first is the macro `BPF_TABLE`. This defines a table (type="hash"), with key
type `key_t` and leaf type `u64` (a single counter). The table name is `stats`,
containing 1024 entries maximum. One can `lookup`, `lookup_or_init`, `update`,
and `delete` entries from the table.
The second concept is the prev argument. This argument is treated specially by
the BCC frontend, such that accesses to this variable are read from the saved
context that is passed by the kprobe infrastructure. The prototype of the args
starting from position 1 should match the prototype of the kernel function being
kprobed. If done so, the program will have seamless access to the function
parameters.
```c
#include <uapi/linux/ptrace.h>
#include <linux/sched.h>

struct key_t {
u32 prev_pid;
u32 curr_pid;
};
// map_type, key_type, leaf_type, table_name, num_entry
BPF_TABLE("hash", struct key_t, u64, stats, 1024);
int count_sched(struct pt_regs *ctx, struct task_struct *prev) {
struct key_t key = {};
u64 zero = 0, *val;

key.curr_pid = bpf_get_current_pid_tgid();
key.prev_pid = prev->pid;

val = stats.lookup_or_init(&key, &zero);
(*val)++;
return 0;
}
```
[Source code listing](examples/task_switch.c)
The userspace component loads the file shown above, and attaches it to the
`finish_task_switch` kernel function (which takes one `struct task_struct *`
argument). The `get_table` API returns an object that gives dict-style access
to the stats BPF map. The python program could use that handle to modify the
kernel table as well.
```python
from bpf import BPF
from time import sleep
b = BPF(src_file="task_switch.c")
fn = b.load_func("count_sched", BPF.KPROBE)
stats = b.get_table("stats")
BPF.attach_kprobe(fn, "finish_task_switch")
# generate many schedule events
for i in range(0, 100): sleep(0.01)
for k, v in stats.items():
print("task_switch[%5d->%5d]=%u" % (k.prev_pid, k.curr_pid, v.value))
```
[Source code listing](examples/task_switch.py)

## Requirements

To get started using this toolchain in binary format, one needs:
Expand All @@ -124,67 +194,4 @@ As of this writing, binary packages for the above requirements are available
in unstable formats. Both Ubuntu and Fedora have 4.2-rcX builds with the above
flags defaulted to on. LLVM provides 3.7 Ubuntu packages (but not Fedora yet).

### Ubuntu - Docker edition

The build dependencies are captured in a [Dockerfile](Dockerfile.ubuntu), the
output of which is a .deb for easy installation.

* Start with a recent Ubuntu install (tested with 14.04 LTS)
* Install a [>= 4.2 kernel](https://kernel.ubuntu.com/~kernel-ppa/mainline/)
with headers
* Reboot
* Install [docker](https://docs.docker.com/installation/ubuntulinux/)
(`wget -qO- https://get.docker.com/ | sh`)
* Run the Dockerfile for Ubuntu - results in an installable .deb
* `git clone https://github.com/iovisor/bcc; cd bcc`
* `docker build -t bcc -f Dockerfile.ubuntu .`
* `docker run --rm -v /tmp:/mnt bcc sh -c "cp /root/bcc/build/*.deb /mnt"`
* `sudo dpkg -i /tmp/libbcc*.deb`
* Run the example
* `sudo python /usr/share/bcc/examples/hello_world.py`

### Fedora - Docker edition

The build dependencies are captured in a [Dockerfile](Dockerfile.fedora), the
output of which is a .rpm for easy installation. This version takes longer since
LLVM needs to be compiled from source.

* Start with a recent Fedora install (tested with F22)
* Install a [>= 4.2 kernel](https://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug/x86_64/)
with headers
* Reboot
* Install [docker](https://docs.docker.com/installation/fedora/)
* Run the Dockerfile for Fedora - results in an installable .rpm
* `git clone https://github.com/iovisor/bcc; cd bcc`
* `docker build -t bcc -f Dockerfile.fedora .`
* `docker run --rm -v /tmp:/mnt bcc sh -c "cp /root/bcc/build/*.rpm /mnt"`
* `sudo rpm -ivh /tmp/libbcc*.rpm`
* Run the example
* `sudo python /usr/share/bcc/examples/hello_world.py`

### Ubuntu - From source

To build the toolchain from source, one needs:
* LLVM 3.7 or newer, compiled with BPF support (default=on)
* Clang 3.7, built from the same tree as LLVM
* cmake, gcc (>=4.7), flex, bison

* Add the [LLVM binary repo](https://llvm.org/apt/) to your apt sources
* `echo "deb https://llvm.org/apt/trusty/ llvm-toolchain-trusty main" | sudo tee /etc/apt/sources.list.d/llvm.list`
* `wget -O - https://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add -`
* `sudo apt-get update`
* Install build dependencies
* `sudo apt-get -y install bison build-essential cmake flex git libedit-dev python zlib1g-dev`
* Install LLVM and Clang development libs
* `sudo apt-get -y install libllvm3.7 llvm-3.7-dev libclang-3.7-dev`
* Install and compile BCC
* `git clone https://github.com/iovisor/bcc.git`
* `mkdir bcc/build; cd bcc/build`
* `cmake .. -DCMAKE_INSTALL_PREFIX=/usr`
* `make -j$(grep -c ^process /proc/cpuinfo)`
* `sudo make install`

## Release notes

* 0.1
* Initial commit
See [INSTALL.md](INSTALL.md) for installation steps on your platform.

0 comments on commit 3151843

Please sign in to comment.