APC Action Applications - Home Page

Frequently Asked Questions v2


Answers for: System Administrator

0. Error: setup.php3 just recycles the same page
1. File Manager Administration
2. How to import big exported slice&data?
3. How can I modify the fonts used in the AA interface?
4. How do I set up Htaccess permissions sync with Reader Management?
5. How to transform the old slice (from AAv1.2-) to the new database structure (used in AAv1.5+)?
6. ERROR: "No slice found for you" - I lost me installation ID ("AA_ID" in config.php3)
7. When are hits counted?
8. How to import lots of data into a slice?
9. What tools are available for importing data
10. How do I make a slice with lots of fields? The web interface takes too long.
11. How do I update my APC-AA installation to the latest version?
12. Error: Access denied for user: 'aadbuser@xxxx'
13. What are the hosting requirements for APC-AA?
14. How to contact the developers
15. Can I run APC-AA on two web servers accessing a common database
16. I have limited access to my box, how do I access PHPLIB
17. How do I create my own validation function
18. How do I fix a corrupt database
19. Can I run APC-AA with IIS and Windows
20. How can I look at the database with Perl?
21. How do I setup my installation for file uploads
22. Using remote or remotec to display APC-AA on another web server
23. How to configure mod_auth_mysql for HTTP authentication with ActionApps authentication system

If hitting "Init" on the setup.php3 page just comes back to the same page, then its probably because your php.ini file contains

"register_globals = Off"

set this to On and restart Apache.

See the manual section 3.7 for instructions.

New settings in config.php3

# mkdir perms, set by variable because constants don't work with octal values $FILEMAN_MODE_DIR = 0770; # create file perms $FILEMAN_MODE_FILE = 0664;

FILEMAN_MODE sets the Unix rights for all files and directories maintained by the File Manager. Specific directories for individual slices are created in FILEMAN_BASE_DIR, specify the name of the directory belonging to a slice in Slice Settings (only superadmins!!). The FILEMAN_BASE_URL is the web path to the FILEMAN_BASE_DIR, and FILEMAN_UPLOAD_TIME_LIMIT (in seconds) is useful when uploading large files.

Slice settings

Superadmins can set for each slice if administrators may access the File Manager and set the directory name. A directory name must be filled in order that administrators may use the File Manager. If the directory does not exist, it is created at the first usage of File Manager.

There is a difference between what a superadmin sees and what a slice administrator sees. The base directory for superadmin is FILEMAN_BASE_DIR, so you see the directory name when entering File Manager and you can jump to the parent directory. But slice administrators have access only to the particular directory and they don't see the directory name.


You can create templates consisting of several files. Some aliases are defined:

Create the templates in directory FILEMAN_BASE_DIR/templates, each in another subdirectory. Use the AA admin / Wizard Templates page to fill info about the templates into database. Write the subdirectory name (without path) and a description.


We have slice data and structure exported to AA.XML file and we want to import it back to the AA. The problem is, that the AA.XML file is 24 MB.

The solution:

The problem could be in PHP setting. Here's what I had to change in php.ini file to get it going:

1. post_max_size: increased from 8M to 32M
2. upload_max_filesize: increased from 2M to 32M

Those first two were key -- from the php log the upload was clearly exceeding both of these parameters. Obviously, if the upload was bigger than 32M (ours was about 24M) this might need to go even bigger.

I also increased these others. I think the upload wouldn't have completed in the default times, but I'm not sure which parts of the operation count towards which of these:

1. max_execution_time: changed from 30 to 120 seconds
2. max_input_time: changed from 30 to 120 seconds
3. memory_limit: changed to 32M There are CSS files in the root directory that you can modify or create a new CSS file and point to it from include/config.php3 (line 139).

Htaccess is updated by AuthMySQL module on the Apache server. The access is granted directly from AA (from auth_group and auth_user tables)

You need to:

1) Install mod_auth_mysql (http://modauthmysql.sourceforge.net/)

(This module is standard part of RedHat Linux distribution (rpm mod_auth_mysql). Be carefull, because there are at least two different modules with the same name but with different httpd.conf options and features. We need the described one and not the one described by Ram: http://actionapps.org/faq/detail.shtml?x=1673 !!!)

2) Then you need set auth_group...... field in Reader managment slice as described here: http://actionapps.org/apc-aa/doc/reader.html#d0e236

3) Set the apache to accept MySQL authentication - something like modifying httpd.conf file:

<Directory /data/www/htdocs/actionapps.org>

AllowOverride AuthConfig FileInfo Options Limit

# Authentication

AuthMySQLHost localhost

AuthMySQLUser aa_db_user

AuthMySQLPassword aa_db_password

AuthMySQLDB aa_db

AuthMySQLUserTable auth_user

AuthMySQLGroupTable auth_group

AuthMySQLNameField username

AuthMySQLPasswordField passwd

AuthMySQLGroupField groups

AuthMySQLNoPasswd off

AuthMySQLCryptedPasswords On



4) Protect the directory by .htaccess file or by similar lines in httpd.conf file:

AuthType Basic

AuthName "ActionApps Ariel Members Area"

<Limit GET>

require group ariel_members



AuthType Basic

AuthName "ActionApps Ariel Parnters Area"

<Limit GET>

require group ariel_partners


5) Done.


There is script /misc/oldDb2Db/move.php3. Script move.php3 is database trnansformation script, which copies whole slice from ActionApps v1.2- to the new database structure, which is used for ActionApps v1.5+.

  1. Go on Admin - Slice structure Import
  2. Copy the content of the /misc/oldDb2Db/oldSliceTemplate.txt file to the import area and press 'Send the slices structure' button. (This slice is then used as template for all imported slices. It makes no sence to repeat steps 1) and 2) for importing second slice !!!
  3. Modify next few lines in this script and fill the
  4. Remove the line just before this coment
  5. Run this script (you have to log as SuperAdmin, then)
  6. Done

What is Done:


After import you have to change the include lines in the pages in order the new slice is called - for example change old line in *.shtml file:

<!--#include virtual="/aa12/slice.php3?slice_id=4e6577735f454e5f746d706c2e2e2e2e"-->

to point to new AAv2.0 installation directory:

<!--#include virtual="/aa20/slice.php3?slice_id=4e6577735f454e5f746d706c2e2e2e2e"-->

The slice id is the same. After that, you shoud review all public pages to make you sure, it works as expected. I do not expect many problems. All features of AAv1.2- as possible to implement in AAv2.0. The biggest problem should be the search form, but it is quite easy to create it manually.

If you get the error: "No slice found for you" after logging into AA after doing a CVS update, then you may have forgotten to fill in the AA_ID in the config.php3 file

If you were a loser (like I have been) and did back-up your AA_ID, it can be retrieved from the AA database...

Using phpMyAdmin or your excellent MySQL skills:
Look for entries in "perms" table that have aa in "object_type" column, "objectid" is your installation ID.

The hit is counted in this cases:

1) with slice.php3
   - if you will display an item with x=24425 url parameter
   - if you will display an item with sh_itm=42567a8736342562782abe782c
   - if you will use banner url parameter (banner=2-38)

2) with view.php3
   - if you display an item with cmd[22]=x-22-24425
     Note 1: if you use more than one item with x command
             (like cmd[23]=x-22-24425-24461-23612) only first
             item is counted)
     Note 2: if you want to display an item and do not want to count
             hit for such item, use 'o' command
             (like cmd[23]=o-22-24425), which works exactly in the same
             way as 'x', but it do not count hits.
   - if you use random parameter (ie. set[23]=random-1)

For speedup of database operations we use log table for hits count, from
which it is time to time copied to item table. You can configure this
behavior in include/constants.php3:

// CountHit probability - how offen write logged hits to item table

This means that after 50 hits (approximately) (in whole AA) the hits are
written to item table (= displayed to users).

For more info see CountHit() function in include/util.php3


The script /misc/file2slice/importer.php3 contains a function importer, which can import a CSV (comma-separated-values) file into your slice.

The data file should contain field names (any names, not from AA) on the first line, separated by your chosen separator. The next lines contain the items, one item per line, fields separated by the same separator.

Johny Bravo, he is a real good guy, johny@bravo.uk, fr, VIP+fools
France Newman, a noname boy, france.newman@noname.org, en, nonames+fools

Here, the separator is comma, but it may be any other string.

The function trimmes each field from whitespace. It has these parametres:

You don't have to set all the parametres - the last one required is postedBy, the next ones have default values.

The "fire" parameter works as a safe mode. You can prepare your data with "fire" set to false and when you are sure that what you see on the screen is what you want to be added to the database (by the StoreItem function), you may set "fire" to true.


The array "actions" should look like this:

$actions = array(
"created_by......" => array("action" => "store", "from" => "AUTHOR"),
"category.......1" => array("action" => "storeparsemulti", "delimiter" => "+", "from" => "CATEGORY"),
"language.......1" => array("action" => "storetrans", "from" => "LANGUAGE", "flag" => 1, "trans"=>array("en"=>"english","fr"=>"french"))

It contains the AA field names followed by how to get their content. You may set flags (e.g. "flag" => 1 means HTML content) with any action.

The actions are as follows:

A fully functional example script

$actions = array(
"category.......1" => array("action" => "storeparsemulti", "delimiter" => ";", "from" => "Category"),
"headline........" => array("action" => "store", "from" => "Title"),
"created_by......" => array("action" => "store", "from" => "Author"),
"full_text......." => array("action" => "store", "from" => "Summary", "flag"=>1)

require "./importer.php3";

Importer ( "aa65a21b285c25f9fe0d4b662919b4b2", // slice iD
	"./books.txt",                      // file name
	"t",                               // field separator
	"uid=ada01,ou=People,ou=AA",        // posted by (there should be a number for sql permissions)
	true,                               // write to DB?
	600);                               // time limit in seconds

There are a number of tools for importing, each has different advantages and disadvantages and each needs configuring to specific requirements.

apc-aa/misc/file2slice/importer.php3: Is highly configurable, and can perform functions on the data, however its complex and requires some PHP knowledge to get to do what its capable of. It is documented below. Note that apc-aa/misc/file2slice/import.php3 is an example of its use.

apc-aa/misc/file2slice/tab2slice.pl is much simpler, but it takes the packed field ids as parameters in the first line of the file being imported, it is documented in the top of the file. (this was apc-aa/misc/tabslice.pl)

apc-aa/misc/file2slice/tab2slice_php/ contains a PHP version that can be used with uploaded files (unlike importer.php which reads the file from the file system). It has to be configured to know the packed ids. It does not have the complex capabilities of import.php3 to manipulate fields during import. See apc-aa/misc/tab2slice_php/README for some basic documentation.

It should be possible to merge the uploadability of tab2slice_php with the automatic configuration of importer.php3 but this has not been done yet.

misc/file2slice/array2constants.php3 is also available for importing constants but requires documentation.

There is an command-line-interface for modifying slice structure (the fields).

See apc-aa/misc/txt2fields/README

This FAQ assumes you did the original installation from CVS (see Installation of ActionApps Doc )

First, check that you really want to update. There is usually a stable release and a developer release. The instructions below will update to the latest release from CVS - which is what most of the people discussing things on the apc-aa-general mailing list are using. This might not be as stable as a release you may be running.

Back-up Your Files and DB

The CVS will write over your current config file, usually located in /apc-aa/includes/config.php3. The key values you will need to re-enter after updating and may not be able to remember are: AA_ID, DB_HOST, DB_NAME, DB_USER, DB_PASSWORD. Without these correct values, AA will not work.

You should also back-up all your apc-aa files, encase the update fails and you need revert back.

Once you have done your back-ups, login to shell on you account and cd to the apc-aa directory and run

cvs -n update

This will display the changes and potential conflict - look for lines starting "C" these are conflicts that need a developer to figure out. You'll have to ask this list if you get one of these.

NOTE: It is common to get 'timed out' type errors from the CVS, which is hosted at SourceForge.net. Just keep trying every few minutes

If it all looks good, run

CVS update -dPAC

This will:
-d Build directories, like checkout does. (if there is new directory in the repository, then it is created)
-P Prune empty directories.
-A Reset any sticky tags/date/kopts. (allways load HEAD branch of the CVS)
-C Overwrite locally modified files with clean repository copies.
(For more options try "cvs --help update")

You should then compare the version number at the top of /apc-aa/includes/config.php3 to see if it is newer then your backed up config.php3 file. If not, you can simplly upload your backed-up version over the new one. If the new config file is different, you will need to manually write in your settings, based on the backed-up version.

Access http://yourhost/apc-aa/sql_update.php3, this will update the database to the latest version. The script always refreshes the database structure to the newest version - no matter if you allready have the newest structure.

The script makes a backup of the tables, but there is not yet a documented way to restore the old version, and note that re-running the script overwrites the last copy of the backup.

Warning: Access denied for user: 'aadbuser@xxxxx' (Using password: YES) in /usr/local/web/phplib/db_mysql.inc on line 73 Database error: pconnect(xanadu.cyborganic.org, aa-user, $Password) failed. MySQL Error: 0 () Please contact foobar@somewhere.com and report the exact error message. Session halted.

Typically this means that the DB_HOST, DB_USER, DB_PASSWORD, DB_NAME setup during editing config.php3 in Install 4.1 don't match the one you gave permissions to in Install4.2. In particular note that if the DB_HOST is absolute e.g. "aa.apc.org" then the permissions are going to have to include the machine name that the Apache server runs on e.g. aadb@bigserver

Requirements for ActionApps Unix Hosting


Please add your comments below about AA installs that have and have not worked for you...

The Action Applications were developed by the Association for Progressive Communications, http://www.apc.org/. They are released as open source and there is a project set up at SourceForge. The Action Applications SourceForge page can be found at http://sourceforge.net/projects/apc-aa/. Yes - this works fine,

You need to setup config.php3 correctly,

Assuming you want the same data to appear on both, then
the key variables seem to be.

AA_INSTAL_URL which can either point to one location, or different locations for each server such as http://www1.yyy.com and http://www2.yyy.com.
DEFAULT_ORG_ID will be the same for both
DB_HOST , DB_USER and DB_PASSWORD will be the same in both cases and point to the database server
DB_NAME will be "aadb" in both cases, i.e. they are using the same set of slices.
AA_ID will be the same in both cases.

Cron feeding to other hosts should be run on one machine only.

If you want totally independent data on each web server, for example if they are serving up totally different slices, then set DB_HOST to different values and AA_ID to different values, and have Cron work on both.
If you are unable to edit php.ini, then you won't be able to change the include path to point at PHPLIB, in this case edit the APC-AA/include/config.php3 to add the following lines.

# PHPlib directory if not on include path
$_PHPLIB["libdir"] = "/www/mysite/phplib/php/";

Change the site to point at the location where you have installed phplib.

You can also access PHPLIB by putting the following line in your .htaccess

php_value include_path ".:/usr/local/lib/php:/usr/local/lib/php/phplib" You can create your own usr_validate.php3 with a user validation function in it (sorry at this point there can only be one for an apc-aa installation, we'll fix that later, if you need it to validate multiple fields you can make it switch based on the field name).

Here is a sample validation function. If the file include/usr_validate.php3 is present it will be included automatically.

// ----- Sample code -------
// returns new value for the field.
// or just return $value;
function usr_validate( $varname, $showname, $value, $err, $f, $fields)
// $varname -- name of variable
// $showname - name of variable in the page.
// $value - value of the input field.
// $err - validated or not.
// Standard way:
// $err["$varname"] = MsgErr(L_ERR_IN." $inputName");
// $f - I DON"T KNOW... please read admin/itemedit.php3
// you can get all the info about the field. include name.
// $field - - all the fields
if (!$value) // no value set in the input field
return "Hey! It is working."; // set default value of the field
else if ($value == "stupid") { // if value is "stupid"
// set error
$err["$varname"] = MsgErr(L_ERR_IN." $showname".". Do not use the word.");
return "fool"; // return error, and change value to "fool".
return $value; // same value. no change.

The action apps software uses the mysql database engine to store its data. The mysql database system is very very reliable.

If the server is interrupted in the middle of a transaction, it can corrupt the database. For example, the servers at SangoNet had a power failure, and one of the mysql tables got corrupted. This shows itself in the actionapps by one of the pages not working and reporting a mysql error about a corrupted database.

It is usually easy to fix a mysql database that has been corrupted. In this case, I just went to /var/mysql (where databases are stored) and checked to see if there were any errors. Mysql uses a program called isamchk to detect and fix errors. This command checks to see if any of the table in any of the databases is corrupted:

/var/mysql > isamchk -s */*.ISM

In this case, the aadb/pagecache.ISM file had two errors. So I ran isamchk in recover mode to fix pagecache.ISM:

/var/mysql > isamchk -r aadb/pagecache.ISM

IIS is not a supported platform for APC-AA or at least it is not tested on this platform. There were some limitations in IIS v4.0 (I'm not sure, how it is in v5.0), which makes AA half-usable. There was a problem of not passing url parameters
to a script, which is included by SSI include into an shtml page.

The requirements are on:
<a href="http://apc-aa.sourceforge.net/apc-aa/doc/install-2.html">apc-aa.sourceforge.net/apc-aa/doc/install-2.html</a>

APC-AA is tested at least on Linux/Apache+MySQL+PHP and on Win98/Apache+MySQL+PHP (as a home developer installation).

The easiest way how to run AA on home Windows machine is to install PHPTriad (Apache, MySQL, PHP), which is really easy, see <a href=http://www.phpgeek.com>www.phpgeek.com</a> Sure - here is a little example that shows how to write a little Perl program to execute and return a SQL string.

#!/usr/bin/perl -w

# this script demonstrates how to use perl to look at the
# mysql database for a slice.
# This particular script looks some of the attributes of a slice's fields

# EDIT NEEDED: set these variables!
# $slice_id $user $password $database $host

# create connection to mysql, using perl DBI module
use DBI;
$dsn = "DBI:mysql:$database:$host";
$dbh = DBI->connect($dsn, $user, $password);

# convert a Hexadecimal input into a packed string
$p_slice_id = pack 'H*', $slice_id;

# create a SQL statement handle, and prepare a template.
# Templates make quoting easier.
my $sth_p = $dbh->prepare(
q{ SELECT id, name, feed, input_show_func from field where slice_id = ? }
) or die $dbh->errstr;

# run the statement, using the packed sliceid, and print the results
$sth_p->execute($p_slice_id) or die $dbh->errstr;
Create a directory under which a sub-directory will be created for each slice,

either create that under one of your sites, or create it somewhere else and

create an alias in httpd.conf to point at it. Make sure this directory is

"rwxrwxr-- nobody.nobody"

Edit apc-aa/include/config.php3, edit the defines IMG_UPLOAD_PATH and

IMG_UPLOAD_URL to point to this directory. Note the trailing "/".

IMG_UPLOAD_TYPE needs configuring, but its not clear what exactly this means.

Michael wrote a perl script called 'remote',( in apc-aa/misc/remote/remote)

'remote' could be useful to groups running action-application
servers, by expanding the number of groups that will want to have slices. Imagine a nonprofit wants to start using the apps for their news page, but does not want to move their site to a webhost that has action applications installed.

Using 'remote', the organization's webmaster could:
1. Ask a server with the action applications to setup a slice for them
2. Include the news items from their slice with 'remote', pulling these items into news.html, on their local webhost.

I think this could be especially true of larger organizations.

Note: If this script is not fast enough, consider using 'apc-aa/misc/remote/remotec', a version of 'remote' with caching, or misc/remote/remotec.php which is in php and should be even faster. Using mod_auth_mysql and .htaccess, http authentication can be configured to make use of the ActionApps user database.

This involves:
1. Installing mod_auth_mysql
2. Configuring .htaccess to use ActionApps user database for authentication.

Installing mod_auth_mysql

(The following method works only for apache with mod_so installed)

1) Download mod_auth_mysql module from http://telia.dl.sourceforge.net/sourceforge/mod-auth-mysql/mod_auth_mysql-3.2.tar.gz ( say in /usr/local/src)
(URL for the project site: http://sourceforge.net/projects/mod-auth-mysql)
2) untar the module ( tar -zxvf mod_auth_mysql-3.2.tar.gz)
3) cd /usr/local/src/mod_auth_mysql-3.2
4) Edit the Makefile to suit your requirement. Edit the APXS and OPTS values. Sample Makefile is provided here:
------------------ Sample Makefile -----------------------------
APXS = /usr/local/apache/bin/apxs # Location of apxs binary
DSO = mod_auth_mysql.so
SRCS = mod_auth_mysql.c
HDRS = mod_auth_mysql.h
OPTS = -I/usr/include/mysql -L/usr/lib/mysql -lmysqlclient

all: $(DSO)

$(DSO): $(SRCS) $(HDRS)
$(APXS) $(APXSFLAGS) -o $(DSO) $(OPTS) -c $(SRCS)

install: $(DSO)

-rm -f *.o $(DSO)
5) run make;make install
6) mod_auth_mysql has been installed now. If successfully installed, httpd.conf will now contain the following line:
LoadModule auth_mysql_module libexec/mod_auth_mysql.so

Configuring mod_auth_mysql to work with APC-AA authentication system

Let the APC-AA DB be aadb
aadb has the table, users with the fields uid, password

now, in your httpd.conf , and in your virtualhost configuration, add the following:

Auth_MySQL_Info myhostname aadbuser aadbpassword

where: myhostname is the host where your aadb database is running
aadbuser is the valid username to access the database
aadbpassword is the valid password to access to access the db.

now, create the .htaccess file, with the following:

Auth_MYSQL on
Auth_MySQL_DB aadb
AuthName "APC-AA Secret Area"
AuthType Basic
Auth_MySQL_Password_Table users
Auth_MySQL_Username_Field uid
Auth_MySQL_Password_Field password
Auth_MySQL_Encryption_Types Plaintext Crypt_DES MySQL
order deny,allow
allow from all
require valid-user

Now, when you try visiting this location in your browser, it should prompt you for the uid/password. Provide you apc-aa uid/password to log in.

Note: Currently, this configuration does not take the group into consideration when authentication. This will be done in the next phase.


This FAQ interface was developed by Jason at Commons.ca

APC: Internet and ICTs for social justice and development APC ActionApps is a free software content management system initiated by the Association for Progressive Communications (APC)
APC - Internet and ICTs for social justice and development