Gentoo Archives: gentoo-announce

From: Geert Bevin <gbevin@×××××××.be>
To: gentoo-announce@g.o
Subject: [gentoo-announce] Portage 1.8.7 released + sandbox explanation
Date: Wed, 30 Jan 2002 13:39:46
Hi all,

Portage 1.8.7 has been released. Since I kinda forgot making an
announcement for v1.8.6, I'm listing here all new features since
Drobbin's last announcement of v1.8.5.

* Emerge now supports package names that are provided without their 
  category. This means that 'emerge sys-apps/portage' is the same as
  'emerge portage'.
* New 'emerge --search' command that searches the portage tree for the 
  provided regular expression. Several search expressions can be 
  provided one after the other in the same command. Type 'emerge --help'
  for detailed information.
* Sadly filesizes were wrongly recorded in the digests files, this bug 
  has been fixed and all digests should have been updated or will be 
  very soon.
* Removal of unnecessary warnings about missing paths that are config 
* New 'dojar' command to make it easy for ebuild authors to install java
  jars in a system unified manner.
* Bugfixes to the version comparison code which should now work 
  correctly with package versions that contain '_pre' suffixes.
* Sandbox bugfixes and speedups.

Thanks a lot to everyone who has helped to make these features and
bugfixes being supplied so quickly!


What follows is intendend for ebuild authors only, don't feel bad if
there's stuff you don't understand ;-)

Since we've been having a lot of questions on the irc channel from
ebuild authors about the recently added sandbox functionality, here's a
short explanation of its use and features.

The sandbox pulls a protective shield around what happens during the
unpack, compile and install phases of an ebuild. This safeguards the
integrity of the filesystem. In fact, during these phases nothing may be
written outside of the PORTAGE_TMPDIR directory and the sandbox prevents
this from happening.
Before, a package could install files directly to the filesystem without
ebuild authors noticing it. Portage needs packages to install into a
temporary staging directory (called the image dir) to be able to keep
track of all the related files. Broken ebuilds not only created
corrupted binary packages (since not all files were collected in the
binary archive), but also left orphaned files dangling on the harddisk
when the package was unmerged.

Whenever such an unauthorized filesystem access occurs, we speak of a
sandbox violation. During these occasions, the sandbox prints out a red
error message and reports a permission denied error to whatever command
executed the action. The ebuild is interrupted and a summary is shown of
all detected violations. This is also saved into a unique logfile whose
name it given in the header of the summary. During the interruption of
the ebuild, several speaker beeps are emitted. This can be configured by
setting the SANDBOX_BEEP variable in /etc/make.conf. It defaults to 3,
but can be set to any value and zero disables the beeps.

To enable the sandbox, all you have to do is add 'sandbox' to the
MAINTAINER variable in make.conf. From that moment onwards, it will be
active for *every* package you unpack, install or compile.

The sandbox is configured through environment variables which contain
path prefixes. The default setup has been carefully examined to allow
some accesses outside of the PORTAGE_TMPDIR directory since certain
languages and procedures need to create temporary files or touch
existing files (python, scrollkeeper, some autoconf scripts, ...). It's
best to leave these settings alone. However sometimes they need to be
changed and the sandbox has to be opened up for certain paths. This can
be done by using the following dedicated ebuild functions :
- addread()
  this has not much use since by default everything is readable
- addwrite()
  add a path prefix to those that are writable
- adddeny()
  revokes any access to the added path prefix
- addpredict()
  denies write access to the added path prefix but isn't seen as a 
  violation, this is occasionally handy when for example permission 
  checks are being made by writing a temporary file into a system 

Remember, only change the sandbox behaviour when you are absolutely sure
there is no other way around the violation and that nothing is installed
that is part of the actual package distribution, otherwise you will be
creating broken packages again! You are supposed to *extensively try
everything* that's possible to fix the makefiles or whatever other
installation method before even thinking about using the above

Finally if there is a package violating the sandbox and you do want to
merge it without changing the MAINTAINER flags in /etc/make.conf and
without fixing the ebuild. The sandbox can be completely disabled by
setting the SANDBOX_DISABLED variable to 1. Example :
    if this creates violations :
        emerge category/package
    this will not:
        SANDBOX_DISABLED="1" emerge category/package

I hope this will clarify this topic a bit. It's planned that the
development docs are updated in a near future.

Best regards,

Geert Bevin
the Leaf sprl/bvba
"Use what you need"           Pierre Theunisstraat 1/47         1030 Brussels
gbevin@×××××××.be             Tel & Fax +32 2 241 19 98