Summary: Converter that uses Schroot to execute commands for the Content recipe
Version:1.0 2008-04-10
Prerequisites: Content recipe, schroot
Status: First Release
Maintainer: Martin Fick
Categories: MarkupWriting

Questions answered by this recipe

  • How can I make it safer to run converters with the Content recipe?
  • How can I make it safer to run external programs to create wiki markup?


The Schroot converter is a converter for the Content recipe which runs programs in a chroot to isolate them from the normal filesystem.


Schroot isolation will reduce the potential malicious effects that a program can have on other files on the system. This converter makes use of the schroot utility, in particular, it makes use of the session capabilities of the schroot utility. Using sessions allows every single conversion to take place in a completely separate filesystem directory from any other conversion, preventing cross conversion information leakage.

While this converter will provide you with filesystem isolation, be aware that it will not provide you with network isolation! This means that if your chroot is compromised and someone is able to take over the process running in the chroot, they may still be able to launch network attacks from this chroot. If the machine running this process is behind a firewall, an attacker may have effectively bypassed your firewall. Depending on how your configure your schroot, you may also be susceptible to a DOS by having your filesystem filed up. If you are concerned about this attack, consider using an lvm-snapshot schroot! Nevertheless, use of this recipe will greatly enhance the security of your installation over the standard FSConverter.

To install this recipe:

  1. Install the Content recipe
  2. Put schrootconverter.phpΔ in your cookbook directory.
  3. Add the following line to your local/config.php: include_once("$FarmD/cookbook/schrootconverter.php");
  4. Configure your schroots (see below)
  5. Register or upgrade your converters (see below)

Registering Converters

For simplicity's sake this converter is designed as a "drop in" replacement for the normal content recipe's FSConverter. Simply "upgrade" an already existing converter which uses the FSConverter and configure a schroot for the converter on your system to use it. However, since some programs are completely unsafe for use with the normal FSConverter, there is naturally also a mechanism to register converters for use with this converter without first registering the converter as a FSConverter. The two converter registering functions are as follows:

A) Upgrading FSConverters:

A converter can be upgraded from an FSConverter by calling the upgrade function:

  SchrootConverterFS($cnv, $schroot)

This function simply takes the name of the converter to upgrade, $cnv, and the name of the $schroot to run it in.

B) Registering New Converters:

A converter can be registered by calling its registering function:

  SchrootConverterReg($intype, $outtype, $schroot, $cmdfmt, $cnv=null, $argfnc=null)

As can be noted, this is somewhat similar to registering an FSConverter except that you need to provide the name of the $schroot to use for the conversion. The remaining arguments will be used in the same way as for the FSConverter, it is best to reference the FSConverter documentation to understand this. Here is an example abcpp registration that could be used with the Music recipe:

  SchrootConverterReg('abcpp', 'abctab', 'abcpp', 'abcpp ${a} < ${i} > ${o}', null, 

  function music_args_abcpp($cp, $cnv, $intype, $outtype, $args) {
    foreach($args as $arg) $out[]= "-$arg";
    return $out;

This program is shown to be unsafe for use with the regular FSConverter in the Content recipe documentation; however this program should be fairly safe inside a minimally configured chroot!

Configuring Schroots

To configure a program for use by the SchrootConverter requires the following steps:

  1. Install schroot 1.1.6 or above on your system
  2. Create a chroot for your program
  3. Configure schroot with your program's chroot

I will not get into how to install schroot, hopefully it will be a simple apt-get or equivalent on your system. The schroot version requires full session support which I do not believe worked properly until 1.1.6.

Create a chroot for your program

There are many ways to go about creating chroots and there are even many helper programs to do this. The exact mechanism depends on what program you are trying to make a chroot for. Unfortunately, there is no exact formula to do this. To add to the complexities of creating a chroot, you must create a chroot that can be used by schroot in a session. This currently means that directory chroots are not good enough. A tar file is probably your best bet. The only additional constraint that your chroot has is that it must contain an empty /tmp directory read/writable by the user running your web server.

In an effort to help with this task, I have created a rudimentary script which takes a program as an argument and attempts to create a simple chroot for it while fetching any shared libraries on which it depends and also including them in the schroot. This script also sets ownership/permissions in a sane fashion for your chroot. To operate properly (set ownerships), this script must be run as root. I suggest you take a quick peek at the program and test it as a normal user first; any errors that you encounter should be permission related. If you do not wish to use this script it will probably still be useful to you as a reference for setting up your chroot manually.

It is probably wise to test your program by chrooting as root into your chroot and verifying that it is indeed functional (and not missing other important files: fonts, config files...) before integrating it with schroot or this recipe.

Configure schroot with your program's chroot

Since you will probably not require much session support for your chroots, a simple schroot configuration with almost no default actions is appropriate. To achieve this, you may want to create some simple "no-action" configuration files like this:

Suggested "no-action" configuration file named none:


Both the mount-none and copyfiles-none files should be empty files!

Here is a sample schroot.conf configuration for your converter using the above configuration file:

  description=your_program for PmWiki's Content Recipe

This should be enough to run your converters.

Once you have a chroot configured in schroot.conf, verifying it manually with schroot can be done like this:

  SID=`schroot -b -c <your_chroot>`                           # start session
  schroot -r -c "$SID" -d /tmp -- <your_program> <prog_args>  # run your_program
  schroot -e -c "$SID"                                        # end session

Release Notes

1.0 - 2008-04-10

  • Initial Release

See Also

  • Content is required by this recipe
  • schroot is required for recipe operation
  • Music - It is possible to upgrade most of the Music recipe's converters to run with schroot using this recipe. This will make the Music recipe more isolated from the rest of your system.



User notes? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.