PageBox: servlet running in sandbox on J2EE PageBox

for
support@pagebox.net PageBox: servlet running in sandbox on J2EE Word version of this document Printer-friendly version of this document Cuckoo generated
Rationale FAQ Dev site PHP version Install Security Customization Demo Distributed Application

PageBox for PHP customization

Deliveries

You can download PageBox for PHP in:

PageBox for PHP repository is made of the following files:

Name

Purpose

repository/admin.php

Administration page

repository/publisher.php

Publisher page

repository/subscriber.php

Subscriber page

repository/select.php

Archive Subscriber first page - Subscriber selection

repository/asubscriber.php

Archive Subscriber second page - Archive selection

repository/download.php

Archive download

repository/environment.php

Page listing the environment and PHP variables and the PHP configuration

repository/audit.php

Page listing Repository events

repository/cleanup.php

Batch cleanup module

repository/cleanup.bat

Windows example of use of cleanup.php

repository/batch.php

Page listing batch events

repository/archive.inc

Classes and functions used by admin.php, publish.php and subscriber.php

repository/pagebox.css

CSS used to display repository pages

repository/pagebox.js

JS functions used by repository pages

repository/logo.gif

PageBox logo

repository/mail.gif

PageBox mail icon

repository/adminUser.rep

Example of adminUser.rep file (user allowed to use admin.php, audit.php, batch.php)

repository/users.rep

Example of users.rep file (users allowed to publish archives)

repository/upload.rep

Example of upload.rep file

PageBox for PHP is made of the following files:

Name

Purpose

pagebox/update.php

PageBox page

pagebox/environment.php

Page listing the environment and PHP variables and the PHP configuration

pagebox/unzip.exe

From Infozip. Example of archive installation

pagebox/inflate.pb

Example of archive installation

pagebox/inflate.bat

Archive installation script (DOS)

pagebox/inflate.sh

Archive installation script (Unix/Linux with gzip compression)

pagebox/inflatez.sh

Archive installation script (Unix/Linux with compress)

pagebox/delete.pb

Example of archive removal

pagebox/delete.bat

Archive removal script (DOS)

pagebox/delete.sh

Archive removal script (Unix/Linux)

pagebox/pagebox.css

CSS used to display repository pages

pagebox/pagebox.js

JS functions used by repository pages

pagebox/logo.gif

PageBox logo

pagebox/mail.gif

PageBox mail icon

Repository

archive.inc

archive.inc contains two core classes:

  • ArchiveRep. ArchiveRep maintains an associative array of the presentations managed by a repository. It has two methods, add to add an presentation to the repository and delete to remove a presentation from the repository.

  • RepoSubs. RepoSubs maintains an associative array of the repository subscribers. It has six methods, subscribe to add a subscriber to the repository and unsubscribe to remove a subscriber from the repository, asubscribe to add an archive subscriber to the repository and unasubscribe to remove an archive subscriber from the repository, add to add a presentation to an archive subscriber, delete to remove a presentation from an archive subscriber.

A subscriber is described by a Subscriber object. The Subscriber object contains an associative array of the presentations deployed or pending for deployment.

When a new presentation is added, it is deployed on every subscriber and added to the Subscriber object.

When a new PageBox subscribes, it receives all presentations defined in ArchiveRep.

Presentations are not automatically added to archive subscribers but when an archive subscriber has subscribed a presentation, it receives presentation updates.

Both ArchiveRep and RepoSubs are serialized and restored:

  • save_archives serializes the repository ArchiveRep in archives.rep

  • restore_archives restores the repository ArchiveRep from archives.rep

  • save_subscribers serializes the repository RepoSubs in subscribers.rep

  • restore_subscribers restores the repository RepoSubs from subscribers.rep

To deploy a presentation a deploy function is invoked. It uses HTTP GET to query pagebox/update.php for the installation of a new presentation.

To undeploy a presentation an undeploy function is invoked. It uses HTTP GET to query pagebox/update.php for the deletion of a presentation.

Note:

archives.rep and subscribers.rep are created and managed by archive.inc.

PHP serialization is fairly readable. However avoid modifying these files by hand.

archive.inc implements:

  • The locking mechanism through lock and unlock functions

  • Logging through the audit function

  • Deploy and undeploy retry through the cleanup function

cleanup is described in admin.php and cleanup.php sections.

The repository locking mechanism uses a file, lock.rep.

  • When it contains 1, the repository is locked and lock returns false.

  • When it contains 0, the repository is unlocked.

We use flock to lock the access to lock.rep.

The mechanism is portable and simple but race conditions are possible when PHP is configured as a module.

subcriber.php

subscriber.php manages a form in GET mode that

  • Lists the Repository subscribers

  • Allows adding and removing subscribers

subscriber.php provides two buttons to remove subscribers Unsub/Unsubscribe and Force.

Force allows removing a PageBox that doesn't exist (anymore) whereas Unsubscribe keeps the subscriber in "pending unsubscribe" state. In that state the subscriber doesn't receive new archives.

select.php

select.php manages a form in GET mode that

  • Lists the Repository archive subscribers

  • Allows adding and removing archive subscribers

select.php provides two buttons to remove archive subscribers Unsub/Unsubscribe and Force.

Force allows removing a PageBox that doesn't exist (anymore) whereas Unsubscribe keeps the archive subscriber in "pending unsubscribe" state. In that state the subscriber doesn't receive archive updates.

select.php provides an Archives button to select archives. When you click Archives, a new window is created to display asubscriber.php.

asubscriber.php

asubscriber.php manages a form in GET mode that

  • Lists the Repository archives

  • Allows selecting subscribed archives

When an archive subscriber has subscribed a presentation, the archive checkbox is set.

You check an archive checkbox to subscribe the presentation (then the presentation is deployed on the subscriber PageBox).

You uncheck an archive checkbox to unsubscribe the presentation (then the presentation is undeployed on the subscriber PageBox).

The actual deploy/undeploy takes place when you click on the Refresh button.

download.php

download.php allows downloading presentations from Repositories without subscription:

When the presentation is updated, it is not deployed on the download site.

The download site doesn't need a PageBox.

download.php displays the Repository meta data:

  • The publisher (owner) of the presentation

  • The documentation posted by the owner

Therefore it should be preferred to directory browsing for Repository download.

publisher.php

publisher.php manages a form in POST mode that

  • Lists the uploaded presentations

  • Allows uploading and removing presentations.

If a users.rep file exists, it should contain a list of allowed publishers, for instance:

publisher1

publisher2

Then:

  1. publisher.php only accepts queries from users defined in users.rep

  2. In case of publication, publisher.php registers the user as the owner of the presentation

  3. publisher.php only displays archives belonging to the user

  4. A user B cannot publish a presentation with the same name as a presentation previously published by a user A

  5. update.php displays the owner of deployed archives

When users.rep is not defined, there is no security check, no publication isolation and no audit.

For production, you should define users.rep and implement security as described in the Security guide.

publisher.php uses POST method upload as defined in RFC 1867.

It moves uploaded presentations from a directory defined in upload.rep to a download directory.

upload.rep should contain the directory where move_uploaded_file($HTTP_POST_FILES["arch"]["tmp_name"], "myPresentation")

stores myPresentation.

In case of Apache with PHP module, it is the Apache directory. For instance on Win 32, if Apache was installed on D drive:

d:\program files\apache group\apache\

Note:

If move_uploaded_file($HTTP_POST_FILES["arch"]["tmp_name"], "myPresentation") stores myPresentation in the repository directory, you don't need to define upload.rep.

Beside the presentation location, publisher.php allows specifying the URL of the presentation documentation. This URL is stored in archives.rep and sent to PageBoxes.

To delete archives, publisher.php provides two buttons, Delete and Force.

In both cases publisher.php send an undeploy(presentation) to all subscribers and removes the presentation file from the repository.

If the undeploy succeeds, the presentation is removed from the archive list of the subscriber.

If the undeploy fails for one subscriber:

  • The presentation is removed from the archive list of the subscriber in case of Force

  • The presentation is kept in the archive list of the subscriber in case of Delete

admin.php

admin.php manages a form in GET mode that:

  • Lists the uploaded presentations

  • Allows removing presentations.

publisher.php is a Presentation publisher tool.

admin.php is the tool of the repository administrator.

It displays all published presentations.

If adminUser.rep is defined it contains the Repository administrator userid, for instance:

admin

Then admin.php only accepts queries coming from the Repository administrator.

To delete archives, admin.php provides two buttons, Delete and Force.

In both cases admin.php send an undeploy(presentation) to all subscribers and removes the presentation file from the repository.

If the undeploy succeeds, the presentation is removed from the archive list of the subscriber.

If the undeploy fails for one subscriber:

  • The presentation is removed from the archive list of the subscriber in case of Force

  • The presentation is kept in the archive list of the subscriber in case of Delete

environment.php

environment.php displays:

  • The Repository Web server environment variables

  • The PHP configuration

  • The PHP environment variables

environment.php uses phpinfo().

audit.php

audit.php displays for each Repository event:

  • The event date and time

  • The host that triggered the event

  • The user that triggered the event

  • The event and its status

A Repository event can be:

  • A page query

  • A subscription, a publication...

Note:

  1. Audit is implemented in archive.inc's lock and audit functions.

  2. Audit events are stored in audit.html

audit.php provides a Clear button to remove the audit.html file.

If adminUser.rep is defined it contains the Repository administrator userid, for instance:

admin

Then audit.php only accepts queries coming from the Repository administrator.

cleanup.php

A PageBox can be unavailable when a deploy or undeploy is issued.

In that case the deployment or undeployment remains in pending state.

The archive.inc's cleanup function retries the deployment/undeployment of archives in pending state.

It can be invoked through the Cleanup button of admin.php.

To call cleanup automatically, you can use a batch command cleanup.php.

cleanup.php expects a single parameter, the download location (where PageBoxes download presentations from the repository).

On Unix, cleanup.php should be defined with execution right (chmod +x cleanup.php).

We wrote a example of batch file for Windows, cleanup.bat:

E:

cd \Program Files\Apache Group\Apache\htdocs\repository

E:\PHP406\php.exe -q cleanup.php localhost:2080/download >>batch.html 2>&1

You probably need to change this data:

  1. E: is the drive where the repository is installed.

  2. \Program Files\Apache Group\Apache\htdocs\repository is the repository path.

  3. E:\PHP406\php.exe is the php.exe path.

  4. localhost:2080/download is the download location.

Both on Unix and Windows you should write the output of cleanup.php in batch.html in the Repository directory to be able to display it with batch.php.

batch.php

batch.php displays the content of batch.html.

It also allows deleting batch.html with the Clear button.

If adminUser.rep is defined it contains the Repository administrator userid, for instance:

admin

Then batch.php only accepts queries coming from the Repository administrator.

PageBox

update.php

update.php manages a form in GET mode that

  1. Lists the deployed presentations

  2. Allows deploying and undeploying presentations.

update.php is invoked by deploy and undeploy functions of archive.inc.

A deploy query has a format:

pagebox_update.php_url?download=presentation&from=repository_download_url

&owner=publisher_userid&doc=documentation_URL&size=presentation_size

&date=presentation_last_modified_date

An undeploy query has a format:

pagebox_update.php_url?delete=presentation

When update.php receives a deploy request it:

  1. Downloads the presentation from the download location

  2. Inflates the presentation according to the content of inflate.pb

  3. Records the presentation in the PbArchives.object

When update.php receives a deploy request it:

  1. Removes the presentation from the PbArchives.object

  2. Removes the inflated presentation according to the content of delete.pb

  3. Delete the downloaded presentation

update.php contains a PbArchives class. PbArchives maintains an associative array of the presentations deployed on the PageBox. It has two methods, add to add an presentation to the PageBox and delete to remove a presentation from the PageBox.

The PbArchives.object is serialized to and restored from pbarchive.pb file.

Note:

pbarchives.pb is created and managed by update.php.

PHP serialization is fairly readable. However avoid modifying this file by hand.

For every presentation extension inflate.pb describes the command run to inflate the presentation. For instance:

zip : inflate.bat

In that case update.php runs the command inflate.bat presentation_without_extension.

inflate.bat can be written like this:

unzip -o %1.zip -d %1

Only presentations whose extension is listed in inflate.pb are installed.

If you don't need to run a command to post process the presentation (for instance a Jar file), write:

Extension : -. For instance:

jar : -

For every presentation extension delete.pb describes the command run to remove the presentation. For instance:

zip:delete.bat

In that case update.php runs the command delete.bat presentation_without_extension.

delete.bat can be written like this:

rmdir /S /Q %1

environment.php

environment.php displays:

  • The Repository Web server environment variables

  • The PHP configuration

  • The PHP environment variables

environment.php uses phpinfo().

Contact:support@pagebox.net
©2001 Alexis Grandemange. Last modified .

Version 0.0.2

  • PageBox only downloads supported presentation (whose extension is defined in inflate.pb)

  • Repository locking

  • Repository audit

  • Repository retry on deploy / undeploy (cleanup)

Version 0.0.3

  • Repository allows subscribing a subset of the Repository presentations (select.php and asubscribe.php)

  • Repository supports presentation download (download.php)

  • Repository allows specifying the URL of the presentation documentation

Table of Content
Deliveries
Repository
archive.inc
subcriber.php
select.php
asubscriber.php
download.php
publisher.php
admin.php
environment.php
audit.php
cleanup.php
batch.php
PageBox
update.php
environment.php