Instrument To Present How Code Runs At The {Hardware} Degree

penguinTrace is meant to assist construct an understanding of how applications run on the {hardware} stage. It offers a technique to see what directions compile to, after which step via these directions and see how they have an effect on machine state in addition to how this maps again to variables within the unique program. A bit extra background is out there on the web site.

penguinTrace begins a web-server which offers an online interface to edit and run code. Code will be developed in C, C++ or Meeting. The ensuing meeting is then displayed and may then be stepped via, with the values of {hardware} registers and variables within the present scope proven.

penguinTrace runs on Linux and helps the AMD64/X86-64 and AArch64 architectures. penguinTrace can run on different working techniques utilizing Docker, a digital machine or via the Home windows Subsystem for Linux (WSL).

penguinTrace requires 64-bit Linux working on a X86-64 or AArch64 processor. It could actually additionally run on a Raspberry Pi working a 64-bit (AArch64) Linux distribution. For different working techniques, it may be run on Home windows 10 utilizing the Home windows Subsystem for Linux (WSL) or in a Docker container. WSL doesn’t help tracee course of isolation.

python
clang
llvm
llvm-dev
libclang-dev
libcap-dev # For containment

Constructing

To construct penguinTrace exterior of a container, clone the repository and run make. The binaries shall be positioned in construct/bin by default.

To construct penguinTrace in Docker, run docker construct -t penguintrace github.com/penguintrace/penguintrace.

Operating

As soon as penguinTrace is constructed, working the penguintrace binary will begin the server.

If in-built a container it might then be run with docker run -it -p 127.0.0.1:8080:8080 --tmpfs /tmp:exec --cap-add=SYS_PTRACE --cap-add=SYS_ADMIN --rm --security-opt apparmor=unconfined penguintrace penguintrace. See Containers for particulars on higher isolating the container.

Then navigate to 127.0.0.1:8080 or localhost:8080 to entry the online interface.

Be aware: To be able to run on port 80, you’ll be able to modify the docker run command to map from port 8080 to port 80, e.g. -p 127.0.0.1:80:8080.

If constructed domestically, you’ll be able to modify the binary to permit it to bind to port 80 with sudo setcap CAP_NET_BIND_SERVICE=+ep penguintrace. It could actually then be run with penguintrace -c SERVER_PORT 80

penguinTrace defaults to port 8080 as it’s meant to be run as an unprivileged person.

Momentary Information

The penguinTrace server makes use of the system momentary listing as a location for compiled binaries and environments for working traced processes. If the PENGUINTRACE_TMPDIR setting variable is outlined, this listing shall be used. It would fall again to the TMPDIR setting variable and eventually the directories specified within the C library.

This should correspond to a listing with out noexec set, if working in a container it’s possible the filesystem may have this set by default.

Networking

By default penguinTrace solely listens on the loopback gadget and IPv4. If the server is configured to hear on all addresses, then additionally setting the server to IPv6 will enable connections on each IPv4 and IPv6, that is the default mode when working in a Docker container.

It is because penguinTrace solely creates a single thread to take heed to connections and so can at present solely bind to a single handle or all addresses.

Session Dealing with

By default penguinTrace runs in a number of session mode, every time code is compiled a brand new session is created. The URL fragment (after the ‘#’) of the UI is up to date with the session id, and this URL can be utilized to reconnect to the identical session.

If working in single session mode every penguinTrace occasion solely helps a single debugging occasion. The net UI will routinely reconnect to a earlier session. To help a number of classes, a number of situations needs to be launched that are listening on completely different ports.

Containers

The docker_build.sh and docker_run.sh scripts present an instance of the right way to run penguinTrace in a Docker container. Dockerfile_noisolate offers an alterative method of working that doesn’t require the SYS_ADMIN functionality however offers much less isolation between the server and the traced processes. The SYS_PTRACE functionality is all the time required for the server to hint processes. misc/apparmor-profile offers an instance AppArmor profile that’s appropriate for working penguinTrace however may have some customisation for the placement of momentary directories and compilers.

AArch64 / Raspberry Pi

penguinTrace will solely run underneath a 64-bit working system. The official working techniques supplied for the Raspberry Pi are all 32-bit, to run penguinTrace one thing akin to pi64 or Arch Linux Arm is required.

Full directions for establishing a 64-bit OS on Raspberry Pi TBD.

Authors

penguinTrace is developed by Alex Beharrell.

License

This undertaking is licensed underneath the GNU AGPL. A non-permissive open supply license is chosen because the intention of this undertaking is academic, and so any by-product works ought to have the supply accessible so that individuals can study from it.

The bundling of the supply code depends on the construction of the repository. By-product works that aren’t forked from a penguinTrace repository might want to modify the Makefile guidelines for static/supply.tar.gz to make sure the modified supply is accurately distributed.

Acknowledgements

penguinTrace makes use of jQuery and CodeMirror for some points of the online interface. Each are licensed underneath the MIT License. It additionally makes use of the Main Mono font which is licensed underneath the Open Font License.