How to install the brat annotation tool on a Linux machine with SELinux enabled

Question

This is a self-answered question that describes how to resolve problems that occur when installing the brat annotation tool, which is used to create annotated corpora for use in NLP, on an ordinary Linux machine that has SELinux enabled. This is based on version 1.3 of the tool.

The installation procedure as documented includes the steps below:

1. Unpack the .tar.gz file in an (Apache) web server directory, typically /var/www/html or $HOME/public_html
2. Possibly rename the unpacked directory from brat-v1.3_Crunchy_Frog to something simple such as brat
3. Enter the directory and run sudo ./install.sh
4. Start the web server (sudo service httpd start) if it wasn't running already

Problem: When following this procedure, any attempt to use brat in a browser (by directing it to http://localhost/brat/index.xhtml fails with the following error messages displayed on screen:

Error: ActiongetCollectionInformation failed on error Internal Server Error
Error: Actionwhoami failed on error Internal Server Error
Error: ActionloadConf failed on error Internal Server Error

The Apache error log (typically found in /var/log/httpd/error_log) also shows errors:

(13)Permission denied: exec of '/var/www/html/new/ajax.cgi' failed, referer: http://localhost/new/index.xhtml
Premature end of script headers: ajax.cgi, referer: http://localhost/new/index.xhtml

How to solve this problem?

Answer 1

This is caused by SELinux. One way to solve it is to disable SELinux, but a somewhat less radical method is to set access rights as required by brat.

The roots of the problem are:

1. brat keeps executable scripts (CGI scripts), static files as well as annotated data all in the same directory, the html directory
2. SELinux is, by default, configured to prevent the execution of CGI scripts from non-CGI directories. Merely changing the Apache configuration does not help here
3. SELinux is also configured to prevent CGI scripts writing data to disk

To modify the SELinux configuration, you need to give access rights to specific files and directories as follows (do this from within the brat installation directory):

$> chcon -t httpd_sys_content_t .
$> chcon -t httpd_sys_script_exec_t *.cgi
$> sudo chcon -R -t httpd_sys_script_rw_t work data

($> represents the command prompt.)

The first command enables read access to the current directory (it may sometimes unnecessary). The second command enables CGI script execution of all files ending in .cgi (this is necessary). The third command enables write access to the work and data directory (also necessary); it needs to be applied again whenever you add files or subdirectories to work or `data.