INSTALLING PHOTO ORGANIZER IN THE OPENBSD CHROOT JAIL

 

 

Introduction

This document is Matt Harrington's contribution, this copy was last updated on January 2, 2004. For the latest version please visit Matt's website at http://photo.underdogma.net/PO-OpenBSD-chroot.txt

This document guides you through the installation of PhotoOrganizer v2.9 on an OpenBSD system inside the chroot jail. While it is intended for OpenBSD and uses various obsd'isms, it may be used as a reference for other systems. The main difference is the handling of the chroot itself and the installation of the packages. These instructions are in addition to the README files supplied in the PO distribution and website, please read those before following these instructions.

Tasks for installing PO on OpenBSD in the chroot Jail:

  1. Install and configure PostgreSQL.
  2. Install PHP4
  3. Install ImageMagick
  4. Install unzip
  5. Install PO
  6. Configure Apache
  7. Troubleshooting

PO v2.9 requires the following pieces of software that are available either as precompiled ports on the OpenBSD ftp site ftp://ftp.openbsd.org or as source in the ports tree:

PACKAGEGROUP REMARK
ImageMagickgraphics/ImageMagick1
PHP4 www/php4 1, 2
PostgreSQL databases/postgresql1

  1. These packages require others that must also be installed.
  2. At current, the php4-core package is not compiled with the proper options meaning that a portion of this software has to be built by hand.

For portability, this document specifies variables instead file system paths. All occurrences of these variables in this document should be replaced with their actual value. These variables are:

VARIABLEDESCRIPTION DEFAULT
$pg_data location of pg database/data
$po_root location of PO install photo
$po_data location of PO data photo_store
$www_chrootapache chroot /var/www

The default values are what I use but can easily be changed.

 

1. Installing PostgreSQL

The instructions for installing and configuring the database are the same as for any operating system. The simplest way is to install the OpenBSD package which will install the relevant files in /usr/local/bin. Create a user to run the database, the database repository, and fire up the database. On my system, it was something like this (as root):

[narse@zord ~]$ setenv PGDATA $pg_data # or export PGDATA=$pg_data
[narse@zord ~]$ sudo -u postgres initdb
[narse@zord ~]$ useradd -c "PostgreSQL Admin" -d $pg_data -g daemon postgres
[narse@zord ~]$ sudo -u postgres pg_ctl -l $pg_data/pg.log start

Special provisions must be made for network database access, as described in Configure section.

 

2. Install PHP4

The installation of php4 is very simple using the OpenBSD packages. The following packages must be installed:

    php4-core
    php4-pear
    php4-extensions
    php4-pgsql

As of PO 2.9, php4-core needs to be compiled with EXIF support or photo uploads will not function. This means compiling php4-core yourself which is quite simple using the ports tree. Download ports.tar.gz from ftp://ftp.openbsd.org, uncompress it, and enter the ports/www/php4/core directory. Edit the Makefile and add the line:

    ' --enable-exif \ '

somewhere in the middle of the CONFIGURE_ARGS definition. Then 'make install' as you would with any other port. This will build and install an EXIF enabled php4 package. For information about the ports tree, see http://openbsd.org.

I have tested this with versions 4.3.3 and 4.3.4 and they both work out of the box. After installing the packages, certain steps may need to be taken. The packages will tell you what commands to execute. The steps will be something like:

    configure apache 'phpxs -s'
    add 'AddType application/x-httpd-php .php' to $www_chroot/conf/httpd.conf
    configure each module '/usr/local/sbin/phpxs -a some_module'

 

3. Install ImageMagick

This step is tricky, it involves a bit of guess and check. Apache will be running in the chroot meaning that all system calls will be relative to $www_chroot instead of /. The installation of ImageMagick must be mirrored into $www_chroot. First install the package as usual. ImageMagick requires several other packages which also must be mirrored. Start by creating the directory tree in $www_chroot (as root):

[narse@zord ~]$ mkdir    $www_chroot/sbin
[narse@zord ~]$ mkdir -p $www_chroot/var/run
[narse@zord ~]$ mkdir -p $www_chroot/usr/X11R6/lib
[narse@zord ~]$ mkdir    $www_chroot/usr/bin
[narse@zord ~]$ mkdir -p $www_chroot/usr/local/lib
[narse@zord ~]$ mkdir    $www_chroot/usr/local/share

I do not know if this is required but a /tmp directory might also be a good idea to have in the chroot jail:

[narse@zord ~]$ mkdir     $www_chroot/tmp
[narse@zord ~]$ chmod 777 $www_chroot/tmp
[narse@zord ~]$ chmod +t  $www_chroot/tmp

Now, start mirroring things into the chroot tree. There are several libraries that are required out of X11, these files are:

    libICE.so.x.x libSM.so.x.x libX11.so.xx libXext.so.xx libXt.so.xx

Copy these files from /usr/X11R6/lib to $www_chroot/usr/X11R6/lib. Now, copy the relevant files from /usr/local/lib to $www_chroot/usr/local/lib:

    libMagick.so.x.x  libintl.so.x.x  libjpeg.so.x.x  librecode.so.x.x
    libiconv.so.x.x   libjbig.so.x.x  libpng.so.x.x   libtiff.so.x.x
    ImageMagick/

From /usr/local/share to $www_chroot/usr/local/share:

    ImageMagick/

I am not sure what binaries are required as it may change depending on the image format, so I chose to copy them all. From /usr/local/bin to $www_chroot/usr/bin:

    Magick++-config  cgimagick  display  iptcutil Magick-config    combine    identify  mogrify animate          convert    import    montage

I am not sure the importance of this next step. On OpenBSD, ldconfig is used to configure the shared library cache. It loads data into /var/run/ld.so.hints based on the libraries found on the system. To allow for shared libraries inside the chroot jail, the jail must have its own ld.so.hints . This means installing and running ldconfig inside the jail. This involves:

[narse@zord ~]$ cp /sbin/ldconfig $www_chroot/sbin/ldconfig
[narse@zord ~]$ touch $www_chroot/var/run/ld.so.hints
[narse@zord ~]$ chroot $www_chroot /sbin/ldconfig -v /usr/X11R6/lib /usr/local/lib

This should print the locations of all of the libraries mirrored into $www_chroot relative to the chroot.

Unfortunately, the PHP system() calls to ImageMagick (convert) are executed inside their own shell instance. This means that you also must put a valid shell inside the chroot.

[narse@zord ~]$ cp /bin/sh $www_chroot/bin/sh

ImageMagick should now be completely installed. This is very easy to test. Find some random large image from http://images.google.com and put it in $www_chroot. For reference, it will be known as $big_image. Run the command (as root):

[narse@zord ~]$ chroot $www_chroot convert -geometry 210x297 /$big_image /small_image

If convert executes without error and there is now an image named $www_chroot/small_image, then ImageMagick works. If there was a problem, then the error message is your best bet, but remember that all path names will be relative to the chroot instead of /.

 

4. Install unzip

PhotoOrganizer supports `bulk uploads', which allow users to upload several photos at once by packing them inside a zip file. At current, PhotoOrganizer uses a system call to `unzip'. Install unzip somewhere PO can find it.

[narse@zord ~]$ cp /usr/local/unzip $www_root/bin

 

5. Install PO

For the most part, the instructions are the same. Either run the install script or follow the FOR NERDS documentation. Just remember that everything must be installed inside $www_chroot or it will not be accessible. For my installation, I chose $www_chroot/$po_root for the Target Directory and $www_chroot/$po_data for the Image Repository. You must connect to the database via a network connection. Even if the database server is the local machine, apache will not have access to the database file socket so you must connect to 127.0.0.1.

Once the installation has completed, it is important that some changes are made in the configuration. PO's configure file is in include/config.php inside the Target Directory. Open this file in an editor. You must change the $image_repository_path to be relative to the chroot. For example, if the repository is $www_chroot/$po_data , set this variable to /$po_data. The $tmp_volume_path may also need to be set if it is not set to /tmp.

 

6. Configure Apache

This portion of the setup can vary greatly, it is mostly a matter of how the user wishes to configure the web server. As long as the PO directory is visible it should function. I chose to install it as a virtual host so that photo.mydomain.net will point only to my photo album. My configuration looks like this:

<Directory /$po_root>
  Options MultiViews Indexes IncludesNoExec
  AllowOverride AuthConfig
  Order allow,deny
  Allow from all
</Directory>
<VirtualHost *>
  DocumentRoot /$po_root
  ServerName photo.mydomain.net
  ServerAlias photos.mydomain.net
  ServerAlias pictures.mydomain.net
  ServerAlias photo
  ServerAlias photos
  ServerAlias pictures
  ErrorLog logs/photo.mydomain.net-error_log
  CustomLog logs/photo.mydomain.net-access_log common
</VirtualHost>

Thats it!

 

7. Troubleshooting

If you have read to this point, you are probably quite frustrated. The first step to take in troubleshooting anything is to take a break, go get a sandwich, then keep reading.

There are several areas where things can go wrong.

  1. PHP does not run

    When accessing the php site, you see only PHP code. This means that PHP has not been installed or configured correctly. If there is an obvious error in the PHP setup inside your apache config file, apache will tell you when you start it. Look for errors. Check log files. Make sure that apache knows to actually run the .php files. Old configurations might be set to run .php3 and not .php.

  2. Cannot login

    This is probably a database error. PO requires the ability to connect to a database when authenticating users and may not give you a good error when it cannot connect. Check your database configuration and assure that the variables in include/config.php are correct. A good place to start is by checking your database logs for failed connections.

  3. Cannot Convert Images

    This is the hardest problem to deal with because it could be a factor of any number of things.

    1. Permissions If the permissions on the $po_data directory are set incorrectly, it will be impossible to store the photos inside the repository. Verify that the user running the database has permissions to write files in $www_chroot/tmp, $www_chroot/$po_data, and all subsequent directories in $www_chroot/$po_data.

    2. Path

      Currently I do now know how to set the path in which system() calls are searched for. The call to convert is not an absolute path so the shell PHP executes has to look for it. Try linking $www_chroot/usr/bin to $www_chroot/bin

    3. Drive Space

      Images are large, make sure there is enough space for the images you are uploading. There must be space in $www_chroot/tmp as well as the repository for the image you are uploading.

    4. Safe_mode

      PHP has a mode called Safe_mode in which it limits the permissions of scripts. It is a good idea to have Safe_mode on at all times but trying PO with it off may give you a hint as to why it does not work. To turn it off, set 'Safe_mode = Off' in your php.ini . I cannot recommend doing this for long periods of time, it may result in remote exploits on your server.

  4. Anything Else

    The best I can say is 'be creative'. Try and walk through the steps that PO would be doing and see what works and what doesn't. Put in some debugging 'print's into the code and see where it gets stuck.

Good luck!