INSTALL.md

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