Gentoo Sandbox Methodology And Troubleshooting


This document is a guide that provides a general framework that novice users/developers can follow in understanding and diagnosing sandbox violation issues. It tries to formalize a troubleshooting methodology so that those uninitiated with the process of debugging sandbox violations will be better equipped to handle such situations when they arise.

Sandbox Violations Explained

The way portage works when you want to emerge some package is as follows:

  1. Portage fetches the needed source tarballs and patches (if necessary).
  2. Portage unpacks the source tarballs to a staging area where all the compilation will take place - portage uses /var/tmp/portage/packagename/work by default
  3. After unpacking and possible patching (this is done in src_unpack() function in the ebuild) portage goes on to do the actual compilation usually just running configure and make in the staging area (ebuilds use ${WORKDIR} to denote this area).
  4. When compilation finishes successfully, portage merges all the files from the staging area to the live filesystem. (usually /, but this can be changed by setting ROOT=''/some path'' when emerging) To avoid bad and/or broken ebuilds from destroying parts or all of the filesystem we need to restrict what areas of the filesystem can portage write to during unpacking and compilation. This is where the sandbox comes into play. By default, the sandbox is set up so that the ebuilds (and everything they run in turn) are restricted to write to the staging area. If an ebuild violates this protected environment known as the sandbox by trying to write outside the staging area - this is denoted as a sandbox violation.
Sandbox Violation: Definition

A sandbox violation is any attempt by an ebuild during an emerge to write outside the portage predefined staging area or protected environment known as the sandbox.


The sandbox is a control mechanism used by portage originally to aid in debugging of ebuilds. Its main purpose is to provide a safe and protected environment for running programs whose functions are not entirely known. Essentially it provides an environment where building of packages can occur without interfering with the operation of the rest of the system. It basically prevents the build process from getting out of control. By now the reasons should be clear why having ebuilds write outside the sandbox can be problematic.

Sandbox Violation Troubleshooting: Principles and Techniques

Do not re-invent the wheel.

Use bugzilla database at as a valuable debugging research tool. Search for the specific sandbox violation error message you have encountered using keyword search and see if there are any other ebuilds that have had the same problems or issues in the past. If there are such instances examine those further to see if anyone has found a solution to that particular problem. Analyze how those corrections were implemented in the affected ebuilds. If there are alternative corrections use the more simple and elegant solution. Then use common sense and intuition to apply a similar fix to your specific problem.

Note: Consider creating a list/database of frequently encountered sandbox violations and their corresponding optimal corrections that users can look through as an initial resource or checklist.

Further Debugging Required

When the above step fails to provide a solution, more work is required to determine and fix why an ebuild wants access outside the sandbox. To fix or prevent sandbox violation problems from occurring a developer has several tools at his/her disposal.

Ebuild command to step through and isolate

The first of which is the ebuild command. This command gives the developer the control and ability to isolate, test and move through the build process step by step. This allows the developer to determine where exactly in the build process the sandbox violation may be occurring.

Sandbox Shell Functions

The second and probably more important and appropriate tool for sandbox violation debugging is the sandboxshell and its various functions. Sandboxshell provides two tools central to debugging sandbox violations: addpredict and addwrite.

Addpredict is a function that allows the developer to simulate a write outside a sandbox in a particular location to fool portage but in fact it doesn't actually allow any real write. Addwrite on the other hand lets the developer override the default sandbox restrictions by allowing an actual write to occur outside the sandbox environment. We prefer addpredict to addwrite in most instances as we don't really want to poke holes in the sandbox - we only pretend we're poking holes. And it happens to be very useful for testing sandbox violations. For instance, if some imaginary ebuild wants to write to /dev/null we should be able to get away with addpredict...basically and never need to use addwrite to check its effects.

Sandbox and Pkg_* Functions

The functions addpredict and addwrite however have limited scope in situations where packages want to make changes on the live file system. For instance packages like apache and mysql both need to add users to the live filesystem which would both be prevented by the sandbox. Addpredict and addwrite do not cover this situation adequately and so other functions are used. This is where the pkg_* functions come into play.

We have for example a function called pkg_postinst() that is callled after the application is merged with the live filesystem. Similarly we have a pkg_preinst() function that can make necessary changes to the live filesystem before merging the application. There are many more such functions and they are all described briefly in the ebuild(5) manpage. The important point to note for our purposes is that the sandbox is disabled when running the pkg_* functions.

Resources: man sandboxshell

Manually Compile

Possible Resources: info automake, info autoconf, Makefiles, strace

About this document ...

Gentoo Sandbox Methodology And Troubleshooting

This document was generated using the LaTeX2HTML translator Version 2002-2 (1.70)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir31558pYSoKL/lyx_tmpbuf0/GentooTroubleShootingMethodologyRev3.tex

The translation was initiated by on 2004-09-02