Installation Instructions
The Dontbug Debugger runs on recent versions of Linux on Intel x86/x64 architectures.
You may run Dontbug on "bare metal" Linux or within a Linux VM on a Mac/Windows host. See below for details.
Dontbug Debugger requires the following software to be installed to run properly:
- Mozilla/RR, version >= 4.3.0
- GNU GDB debugger, version >= 7.11.1
- A PHP installation, version 7.0.x
- Xdebug, version >= 2.4.0 (to which a very small, Dontbug specific patch has been applied)
- A PHP IDE like Netbeans, Eclipse PDT or PhpStorm. The first two IDEs are open source and available for free while the last one is available free for a 30-day trial period. These IDEs have been tested to work with dontbug but in general, any PHP IDE that supports Xdebug should work.
Running Dontbug on a "bare metal" installation of Linux ("bare metal" means Linux is not being run in a virtual machine) is the recommended way to run Dontbug. This configuration may, sadly, not be feasible for many users -- see other alternatives below.
You will need to run Dontbug within a Linux VM if you're on macOS.
Sorry, you cannot use VirtualBox as it does not have the ability to virtualize CPU performance counters ("PMU Virtualization") which are necessary for rr to run.
You can use VMWare Fusion instead. The VMWare Fusion hypervisor is a paid product but you should able to download and use it for a 30-day trial period for free.
Make sure code profiling is enabled in your VMWare Fusion VM settings.
The Parallels Desktop hypervisor says it supports PMU Virtualization but it does not seem to work with rr.
The situation is similar to that of macOS. You'll need to run Dontbug in a Linux VM. But the hypervisor should be able to support performance counter virtualization, so like macOS, you cannot use VirtualBox.
Running a Linux VM using the VMWare workstation hypervisor should work for Windows. Its a paid product but you should be able to download and use it for a 30-day trial period for free. Please make sure code profiling is enabled in your VMWare Workstation settings (see screenshot in "Running dontbug on macOS").
You can run Dontbug on a Linux VM on Linux by using libvirt/KVM. The cpu mode should be host-passthrough.
Development of dontbug has taken place on Ubuntu Xenial (16.04) so its recommended to use Xenial if you can. Ubuntu 14.04 should work too.
However, you should have absolutely no problems running running dontbug on other, relatively recent Linux distributions. If you face any problems, please file a bug.
An advantage of using Ubuntu Xenial is that the package manager apt has GDB 7.11.1 which is a minimum requirement for dontbug. You may need to compile GDB from source for other distributions.
In general, the bottleneck for using dontbug is rr. If rr works then you're going to be able to get Dontbug working easily. If you're running into strange issues, try consulting RR documentation in addition to Dontbug documentation.
These are step by step instructions for installing Dontbug in your Linux distribution. The hope is to automate this step-by-step install using installers/install scripts in the future.
When you start here you should either be:
- Running in a "bare metal" Linux distribution
- Running in a Linux VM on the KVM/libvirt hypervisor with
cpu modeashost-passthrough - Running in a Linux VM on a hypervisor on macOS/Windows that supports performance counter virtualization (e.g. VMWare Fusion/Workstation)
These instructions are for Debian/Ubuntu based systems. Please substitute the appropriate package manager (e.g. yum, zypper etc.) for other systems like Fedora/OpenSuse etc.
This one is easy: mozilla/rr binary releases are available on github.
For example for x64, debian based systems:
$ wget https://github.com/mozilla/rr/releases/download/4.4.0/rr-4.4.0-Linux-x86_64.deb
$ sudo dpkg -i rr-4.3.0-Linux-x86_64.debIf you want to build rr from source, please see here. Don't forget to git checkout 4.4.0 before building!
Ubuntu Xenial (16.04) and later come with GDB 7.11.1 which is the minimum requirement for dontbug. sudo apt install gdb is all that you need to do. If GDB 7.11.1 is not available then you can build it from source.
After installing GDB and RR, lets test RR:
# record the execution of 'ls' command
$ rr record ls
# replay 'ls' using gdb
$ rr replayrr replay should start up GDB. At the GDB prompt type in continue and press <enter>. If you're able to see a listing of the directory again, that means that rr has successfully recorded and replayed the execution of the ls command.
This is a quick test to ensure that RR is working properly. Ensure this works before going onto further steps.
You can install PHP 7.0 from your package manager. If you don't have PHP 7.0 in your distribution then you'll have to built PHP 7.0 from source.
$ sudo apt install php7.0 php7.0-mysql php7.0-cli
# Useful to manage mysql databases from a GUI interface
$ sudo apt install mysql-server mysql-client phpmyadminXdebug is required by Dontbug. Currently, a small patch needs to applied when building Xdebug. These instructions assume that you're using the distro packaged PHP 7.0 binaries. If you plan on building PHP 7.0 yourself then follow these instructions, instead, to install the patched Xdebug.
# Install the Xdebug package. This step is merely for convenience as it gives us
# some .ini configuration for free. All we're going to do is use the same
# configuration but replace xdebug.so with the one we compile. If you're
# fussy you can skip the next step (sudo apt install php-xdebug) but you
# then need to make sure all your .ini configuration is OK
$ sudo apt install php-xdebug
$ cd ~
$ git clone https://github.com/xdebug/xdebug.git
$ cd xdebug
$ git checkout xdebug_2_4
$ wget https://raw.githubusercontent.com/sidkshatriya/dontbug/master/ext/dontbug/xdebug_2_4.make_extern.dontbug.patch
$ git apply xdebug_2_4.make_extern.dontbug.patch
$ phpize
$ ./configure --with-php-config=/usr/bin/php-config7.0 --prefix=/usr
$ make
# Note that we need sudo here to save xdebug.so in /usr/lib/php/20151012/
$ sudo make install
# Match the permissions of rest of the extensions in /usr/lib/php/20151012/
$ sudo chmod u=rw,g=r,o=r /usr/lib/php/20151012/xdebug.so
# Confirm that xdebug.so permissions are like the rest of the extensionsMake sure there is a file xdebug.ini and its there in /etc/php/7.0/mods-available/. If not, create it.
It should look something like this (but can have more stuff in it):
# xdebug.ini
zend_extension=xdebug.so
Finally, enable Xdebug:
$ sudo phpenmod xdebugYou can verify that Xdebug has been installed properly by checking php -v to see the Xdebug version string 2.4.XXX. For example:
$ php -v
PHP 7.0.8-0ubuntu0.16.04.2 (cli) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
with Xdebug v2.4.2-dev, Copyright (c) 2002-2016, by Derick Rethans
Don't proceed unless you've got this working.
The Zend OPCache does not seem to work well with Dontbug. You can check if it's enabled by seeing the output of php -m. If it's enabled, please disable it by making the appropriate .ini file edit. If you're using Ubuntu Xenial you can disable it by doing sudo phpdismod opcache.
Finally, you'll need to build Dontbug from source. You'll need to have a golang development environment installed.
Install the Linux amd64 golang binary package and follow the instructions on on how to setup a golang development environment. You could install golang using apt but that is not recommended as it does not have the latest golang versions available.
Make sure you have the GOPATH environment variable set and have $GOPATH/bin in your $PATH.
Finally, compile dontbug from its go sources:
$ go get github.com/sidkshatriya/dontbug
$ go install github.com/sidkshatriya/dontbugYou should see dontbug sources at $GOPATH/src/github.com/sidkshatriya/dontbug and the compiled binary at $GOPATH/bin/dontbug.
Try running:
$ dontbug record --help
The Dontbug Debugger needs to know the location of Xdebug headers.
$ cd $GOPATH/src/github.com/sidkshatriya/dontbug
$ cd ext/dontbug
# create a symlink "xdebug" to the xdebug sources compiled earlier
$ ln -s ~/xdebug xdebugDon't miss this step or Dontbug will not work.
Create a $HOME/.dontbug.yaml file, though you may not need to, in most cases.
# Uncomment '#' wherever required
# Optional, **only** needed if rr is not in $PATH
# with-rr: /path-to/rr
# Optional, **only** needed if you built PHP 7.0 from source
# with-php: /path-to-custom-php-build-dir>/bin/php
# Optional, **only** if gdb is not in $PATH
# with-gdb: /path-to/gdbTL; DR: Dontbug is a development tool and can be used in most development environments without much fuss. Usage on publicly accessible servers/mission-critical/security-sensitive environments requires greater caution and understanding of Dontbug and the software it depends on like RR, GDB, Xdebug and PHP.
Please keep these notes in mind when installing and subsequently using Dontbug:
The Dontbug Debugger uses the PHP built-in webserver when recording non-command line PHP applications. From the link:
Warning This web server was designed to aid application development. It may also be useful for testing purposes or for application demonstrations that are run in controlled environments. It is not intended to be a full-featured web server. It should not be used on a public network.
When Dontbug starts the PHP built-in webserver it listens on the loopback interface 127.0.0.1, specifically port 8088. Listening on 127.0.0.1 should prevent public network access (unless you're doing stuff like port forwarding to/from 127.0.0.1:8088 etc.). This default listen IP can be changed using the --server-listen option. So, if you change the default listen IP to a publicly accessible address please be aware of this warning.
If you use Dontbug on production/mission critical/security sensitive environments please exercise the usual caution as you would any other software. As a start, its most important to get a good understanding of Dontbug to see if you there are any things you need to consider. For example you may need to take precautions like block Dontbug/Xdebug/RR specific TCP ports in your firewall from external access (or more simply, configure your firewall to only expose TCP ports that absolutely need to be contactable externally). There might be other considerations like user/group permissions of the RR and Dontbug executables etc. You will need to figure out the specific precautions that need to be taken for your particular setup.
Additionally, as we have seen from the installation instructions above, Dontbug depends on other software projects like Mozilla/RR, GDB, PHP and Xdebug. The security related tips or suggestions that apply to these projects should obviously be kept in mind also when using Dontbug.