1# Installing BCC 2 3* [Kernel Configuration](#kernel-configuration) 4* [Packages](#packages) 5 - [Ubuntu](#ubuntu---binary) 6 - [Fedora](#fedora---binary) 7 - [Arch](#arch---aur) 8 - [Gentoo](#gentoo---portage) 9 - [openSUSE](#opensuse---binary) 10 - [RHEL](#rhel---binary) 11* [Source](#source) 12 - [Debian](#debian---source) 13 - [Ubuntu](#ubuntu---source) 14 - [Fedora](#fedora---source) 15 - [openSUSE](#opensuse---source) 16 - [Amazon Linux](#amazon-linux---source) 17* [Older Instructions](#older-instructions) 18 19## Kernel Configuration 20 21In general, to use these features, a Linux kernel version 4.1 or newer is 22required. In addition, the kernel should have been compiled with the following 23flags set: 24 25``` 26CONFIG_BPF=y 27CONFIG_BPF_SYSCALL=y 28# [optional, for tc filters] 29CONFIG_NET_CLS_BPF=m 30# [optional, for tc actions] 31CONFIG_NET_ACT_BPF=m 32CONFIG_BPF_JIT=y 33CONFIG_HAVE_BPF_JIT=y 34# [optional, for kprobes] 35CONFIG_BPF_EVENTS=y 36``` 37 38There are a few optional kernel flags needed for running bcc networking examples on vanilla kernel: 39 40``` 41CONFIG_NET_SCH_SFQ=m 42CONFIG_NET_ACT_POLICE=m 43CONFIG_NET_ACT_GACT=m 44CONFIG_DUMMY=m 45CONFIG_VXLAN=m 46``` 47 48Kernel compile flags can usually be checked by looking at `/proc/config.gz` or 49`/boot/config-<kernel-version>`. 50 51# Packages 52 53## Ubuntu - Binary 54 55The stable and the nightly packages are built for Ubuntu Xenial (16.04), Ubuntu Artful (17.10) and Ubuntu Bionic (18.04). The steps are very straightforward, no need to upgrade the kernel or compile from source! 56 57**Stable and Signed Packages** 58 59```bash 60sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 4052245BD4284CDD 61echo "deb https://repo.iovisor.org/apt/$(lsb_release -cs) $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/iovisor.list 62sudo apt-get update 63sudo apt-get install bcc-tools libbcc-examples linux-headers-$(uname -r) 64``` 65(replace `xenial` with `artful` or `bionic` as appropriate). Tools will be installed under /usr/share/bcc/tools. 66 67**Nightly Packages** 68 69```bash 70echo "deb [trusted=yes] https://repo.iovisor.org/apt/xenial xenial-nightly main" | sudo tee /etc/apt/sources.list.d/iovisor.list 71sudo apt-get update 72sudo apt-get install bcc-tools libbcc-examples linux-headers-$(uname -r) 73``` 74(replace `xenial` with `artful` or `bionic` as appropriate) 75 76**Ubuntu Packages** 77 78The previous commands will install the latest bcc from the iovisor repositories. It is also available from the standard Ubuntu multiverse repository, under the package name `bpfcc-tools`. 79 80```bash 81sudo apt-get install bpfcc-tools linux-headers-$(uname -r) 82``` 83 84The tools are installed in /sbin with a -bpfcc extension. Try running `sudo opensnoop-bpfcc`. 85 86## Fedora - Binary 87 88Ensure that you are running a 4.2+ kernel with `uname -r`. If not, install a 4.2+ kernel from 89http://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug, for example: 90 91```bash 92sudo dnf config-manager --add-repo=http://alt.fedoraproject.org/pub/alt/rawhide-kernel-nodebug/fedora-rawhide-kernel-nodebug.repo 93sudo dnf update 94# reboot 95``` 96 97**Nightly Packages** 98 99Nightly bcc binary packages for Fedora 25, 26, 27, and 28 are hosted at 100`https://repo.iovisor.org/yum/nightly/f{25,26,27}`. 101 102To install: 103```bash 104echo -e '[iovisor]\nbaseurl=https://repo.iovisor.org/yum/nightly/f27/$basearch\nenabled=1\ngpgcheck=0' | sudo tee /etc/yum.repos.d/iovisor.repo 105sudo dnf install bcc-tools kernel-headers kernel-devel 106``` 107 108**Stable and Signed Packages** 109 110Stable bcc binary packages for Fedora 25, 26, 27, and 28 are hosted at 111`https://repo.iovisor.org/yum/main/f{25,26,27}`. 112 113```bash 114echo -e '[iovisor]\nbaseurl=https://repo.iovisor.org/yum/main/f27/$basearch\nenabled=1' | sudo tee /etc/yum.repos.d/iovisor.repo 115sudo dnf install bcc-tools kernel-devel-$(uname -r) kernel-headers-$(uname -r) 116``` 117 118## Arch - AUR 119 120Upgrade the kernel to minimum 4.3.1-1 first; the ```CONFIG_BPF_SYSCALL=y``` configuration was not added until [this kernel release](https://bugs.archlinux.org/task/47008). 121 122Install these packages using any AUR helper such as [pacaur](https://aur.archlinux.org/packages/pacaur), [yaourt](https://aur.archlinux.org/packages/yaourt), [cower](https://aur.archlinux.org/packages/cower), etc.: 123``` 124bcc bcc-tools python-bcc python2-bcc 125``` 126All build and install dependencies are listed [in the PKGBUILD](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=bcc) and should install automatically. 127 128## Gentoo - Portage 129 130First of all, upgrade the kernel of your choice to a recent version. For example: 131``` 132emerge sys-kernel/gentoo-sources 133``` 134Then, configure the kernel enabling the features you need. Please consider the following as a starting point: 135``` 136CONFIG_BPF=y 137CONFIG_BPF_SYSCALL=y 138CONFIG_NET_CLS_BPF=m 139CONFIG_NET_ACT_BPF=m 140CONFIG_BPF_JIT=y 141CONFIG_BPF_EVENTS=y 142``` 143Finally, you can install bcc with: 144``` 145emerge dev-util/bcc 146``` 147The appropriate dependencies (e.g., ```clang```, ```llvm``` with BPF backend) will be pulled automatically. 148 149## openSUSE - Binary 150 151For openSUSE Leap 42.2 (and later) and Tumbleweed, bcc is already included in the official repo. Just install 152the packages with zypper. 153 154```bash 155sudo zypper ref 156sudo zypper in bcc-tools bcc-examples 157``` 158 159## RHEL - Binary 160 161For RHEL 7.6, bcc is already included in the official yum repository as bcc-tools. As part of the install, the following dependencies are installed: bcc.x86_64 0:0.6.1-2.el7 ,llvm-private.x86_64 0:6.0.1-2.el7 ,python-bcc.x86_64 0:0.6.1-2.el7,python-netaddr.noarch 0:0.7.5-9.el7 162 163``` 164yum install bcc-tools 165``` 166 167# Source 168 169## Debian - Source 170### Jessie 171#### Repositories 172 173The automated tests that run as part of the build process require `netperf`. Since netperf's license is not "certified" 174as an open-source license, it is in Debian's `non-free` repository. 175 176`/etc/apt/sources.list` should include the `non-free` repository and look something like this: 177 178``` 179deb http://httpredir.debian.org/debian/ jessie main non-free 180deb-src http://httpredir.debian.org/debian/ jessie main non-free 181 182deb http://security.debian.org/ jessie/updates main non-free 183deb-src http://security.debian.org/ jessie/updates main non-free 184 185# wheezy-updates, previously known as 'volatile' 186deb http://ftp.us.debian.org/debian/ jessie-updates main non-free 187deb-src http://ftp.us.debian.org/debian/ jessie-updates main non-free 188``` 189 190BCC also requires kernel version 4.1 or above. Those kernels are available in the `jessie-backports` repository. To 191add the `jessie-backports` repository to your system create the file `/etc/apt/sources.list.d/jessie-backports.list` 192with the following contents: 193 194``` 195deb http://httpredir.debian.org/debian jessie-backports main 196deb-src http://httpredir.debian.org/debian jessie-backports main 197``` 198 199#### Install Build Dependencies 200 201Note, check for the latest `linux-image-4.x` version in `jessie-backports` before proceeding. Also, have a look at the 202`Build-Depends:` section in `debian/control` file. 203 204``` 205# Before you begin 206apt-get update 207 208# Update kernel and linux-base package 209apt-get -t jessie-backports install linux-base linux-image-4.9.0-0.bpo.2-amd64 linux-headers-4.9.0-0.bpo.2-amd64 210 211# BCC build dependencies: 212apt-get install debhelper cmake libllvm3.8 llvm-3.8-dev libclang-3.8-dev \ 213 libelf-dev bison flex libedit-dev clang-format-3.8 python python-netaddr \ 214 python-pyroute2 luajit libluajit-5.1-dev arping iperf netperf ethtool \ 215 devscripts zlib1g-dev libfl-dev 216``` 217 218#### Sudo 219 220Adding eBPF probes to the kernel and removing probes from it requires root privileges. For the build to complete 221successfully, you must build from an account with `sudo` access. (You may also build as root, but it is bad style.) 222 223`/etc/sudoers` or `/etc/sudoers.d/build-user` should contain 224 225``` 226build-user ALL = (ALL) NOPASSWD: ALL 227``` 228 229or 230 231``` 232build-user ALL = (ALL) ALL 233``` 234 235If using the latter sudoers configuration, please keep an eye out for sudo's password prompt while the build is running. 236 237#### Build 238 239``` 240cd <preferred development directory> 241git clone https://github.com/iovisor/bcc.git 242cd bcc 243debuild -b -uc -us 244``` 245 246#### Install 247 248``` 249cd .. 250sudo dpkg -i *bcc*.deb 251``` 252 253## Ubuntu - Source 254 255To build the toolchain from source, one needs: 256* LLVM 3.7.1 or newer, compiled with BPF support (default=on) 257* Clang, built from the same tree as LLVM 258* cmake (>=3.1), gcc (>=4.7), flex, bison 259* LuaJIT, if you want Lua support 260 261### Install build dependencies 262``` 263# Trusty and older 264VER=trusty 265echo "deb http://llvm.org/apt/$VER/ llvm-toolchain-$VER-3.7 main 266deb-src http://llvm.org/apt/$VER/ llvm-toolchain-$VER-3.7 main" | \ 267 sudo tee /etc/apt/sources.list.d/llvm.list 268wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key | sudo apt-key add - 269sudo apt-get update 270 271# For bionic 272sudo apt-get -y install bison build-essential cmake flex git libedit-dev \ 273 libllvm6.0 llvm-6.0-dev libclang-6.0-dev python zlib1g-dev libelf-dev 274 275# For other versions 276sudo apt-get -y install bison build-essential cmake flex git libedit-dev \ 277 libllvm3.7 llvm-3.7-dev libclang-3.7-dev python zlib1g-dev libelf-dev 278 279# For Lua support 280sudo apt-get -y install luajit luajit-5.1-dev 281``` 282 283### Install and compile BCC 284``` 285git clone https://github.com/iovisor/bcc.git 286mkdir bcc/build; cd bcc/build 287cmake .. -DCMAKE_INSTALL_PREFIX=/usr 288make 289sudo make install 290``` 291 292## Fedora - Source 293 294### Install build dependencies 295 296``` 297sudo dnf install -y bison cmake ethtool flex git iperf libstdc++-static \ 298 python-netaddr python-pip gcc gcc-c++ make zlib-devel \ 299 elfutils-libelf-devel 300sudo dnf install -y luajit luajit-devel # for Lua support 301sudo dnf install -y \ 302 http://repo.iovisor.org/yum/extra/mageia/cauldron/x86_64/netperf-2.7.0-1.mga6.x86_64.rpm 303sudo pip install pyroute2 304``` 305 306### Install binary clang 307 308``` 309# FC22 310wget http://llvm.org/releases/3.7.1/clang+llvm-3.7.1-x86_64-fedora22.tar.xz 311sudo tar xf clang+llvm-3.7.1-x86_64-fedora22.tar.xz -C /usr/local --strip 1 312 313# FC23 314wget http://llvm.org/releases/3.9.0/clang+llvm-3.9.0-x86_64-fedora23.tar.xz 315sudo tar xf clang+llvm-3.9.0-x86_64-fedora23.tar.xz -C /usr/local --strip 1 316 317# FC24 and FC25 318sudo dnf install -y clang clang-devel llvm llvm-devel llvm-static ncurses-devel 319``` 320 321### Install and compile BCC 322``` 323git clone https://github.com/iovisor/bcc.git 324mkdir bcc/build; cd bcc/build 325cmake .. -DCMAKE_INSTALL_PREFIX=/usr 326make 327sudo make install 328``` 329 330## openSUSE - Source 331 332### Install build dependencies 333 334``` 335sudo zypper in bison cmake flex gcc gcc-c++ git libelf-devel libstdc++-devel \ 336 llvm-devel clang-devel pkg-config python-devel python-setuptools python3-devel \ 337 python3-setuptools 338sudo zypper in luajit-devel # for lua support in openSUSE Leap 42.2 or later 339sudo zypper in lua51-luajit-devel # for lua support in openSUSE Tumbleweed 340``` 341 342### Install and compile BCC 343``` 344git clone https://github.com/iovisor/bcc.git 345mkdir bcc/build; cd bcc/build 346cmake -DCMAKE_INSTALL_PREFIX=/usr \ 347 -DLUAJIT_INCLUDE_DIR=`pkg-config --variable=includedir luajit` \ # for lua support 348 .. 349make 350sudo make install 351cmake -DPYTHON_CMD=python3 .. # build python3 binding 352pushd src/python/ 353make 354sudo make install 355popd 356``` 357 358## Amazon Linux - Source 359 360Tested on Amazon Linux AMI release 2018.03 (kernel 4.14.47-56.37.amzn1.x86_64) 361 362### Install packages required for building 363``` 364# enable epel to get iperf, luajit, luajit-devel, cmake3 (cmake3 is required to support c++11) 365sudo yum-config-manager --enable epel 366 367sudo yum install -y bison cmake3 ethtool flex git iperf libstdc++-static python-netaddr gcc gcc-c++ make zlib-devel elfutils-libelf-devel 368sudo yum install -y luajit luajit-devel 369sudo yum install -y http://repo.iovisor.org/yum/extra/mageia/cauldron/x86_64/netperf-2.7.0-1.mga6.x86_64.rpm 370sudo pip install pyroute2 371sudo yum install -y ncurses-devel 372``` 373 374### Install clang 3.7.1 pre-built binaries 375``` 376wget http://releases.llvm.org/3.7.1/clang+llvm-3.7.1-x86_64-fedora22.tar.xz 377tar xf clang* 378(cd clang* && sudo cp -R * /usr/local/) 379``` 380 381### Build bcc 382``` 383git clone https://github.com/iovisor/bcc.git 384pushd . 385mkdir bcc/build; cd bcc/build 386cmake3 .. -DCMAKE_INSTALL_PREFIX=/usr 387time make 388sudo make install 389popd 390``` 391 392### Setup required to run the tools 393``` 394sudo yum -y install kernel-devel-$(uname -r) 395sudo mount -t debugfs debugfs /sys/kernel/debug 396``` 397 398### Test 399``` 400sudo /usr/share/bcc/tools/execsnoop 401``` 402 403# Older Instructions 404 405## Build LLVM and Clang development libs 406 407``` 408git clone http://llvm.org/git/llvm.git 409cd llvm/tools; git clone http://llvm.org/git/clang.git 410cd ..; mkdir -p build/install; cd build 411cmake -G "Unix Makefiles" -DLLVM_TARGETS_TO_BUILD="BPF;X86" \ 412 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install .. 413make 414make install 415export PATH=$PWD/install/bin:$PATH 416``` 417