ViSUS Server
The ViSUS Server, also known as mod_visus, is an Apache or IIS module that provides simple access to remote multiresolution IDX datasets.
Contents
Apache Server module installation
Install Apache
For OpenSuse: follow the instructions in http://doc.opensuse.org/documentation/html/openSUSE/opensuse-reference/cha.apache2.html
sudo zypper in apache2-devel
For Ubuntu :
sudo apt-get install apache2
sudo apt-get install apache2-dev
Find the directory where the Apache Server is, and type:
WWW=/srv/www
Find the directory where the Apache Modules are, and type:
MODULES=/usr/lib64/apache2
Find where the Apache error log is, and type:
ERROR_FILE=/var/log/apache2/error_log
Copy in WWW directory your visus.config file (see ViSUS configuration file for reference):
mkdir $WWW/visus sudo cp visus.config $WWW/visus/visus.config
Note: the datasets in the visus.config file in order to be accessed from remote have to specify the attribute permissions="public"
in their declaration.
Make sure that the visus.log file has read and write permissions by root/apache user. For example:
sudo rm -f $WWW/visus/visus.log sudo touch $WWW/visus/visus.log
Change permissions to the directory (a+rw is not what you want in production!)
sudo chmod -R a+rw $WWW
Make sure that all datasets listed in $WWW/visus/visus.config are accessible by root/apache user For example you can do a:
chmod -R a+r /path/to/visus/dataset
Build Visus Apache module
mkdir -p build/mod_visus
cd build/mod_visus
cmake -DVISUS_BUILD_MODVISUS=1 \ -DVISUS_SERVER_CONFIG_FILE="$WWW/visus/visus.config" \ -DVISUS_LOG_FILE="$WWW/visus/visus.log" \ -DCMAKE_BUILD_TYPE=Release ../..
make -j 32
Note: If you are having fPIC error message, configure in ccmake and add a single space in CMAKE_CXX_FLAGS and CMAKE_C_FLAG.
Install the module
Install the visus module in the proper Apache module directory:
sudo cp libmod_visus.so $MODULES/mod_visus.so sudo chmod 644 $MODULES/mod_visus.so
Edit the file /etc/sysconfig/apache2, look for for APACHE_MODULES and add "visus"
sudo vi /etc/sysconfig/apache2
Do a sudo vi /etc/apache2/httpd.conf
and add to the end these lines:
LoadModule visus_module modules/mod_visus.so <Location /mod_visus> SetHandler visus DirectorySlash Off </Location>
See the next section on Security for Apache server for more details about access configuration for the users.
Supported Requests
The API for the server facilitates a variety of access modes, including direct block level retrieval as well as requesting data within a specified region of interest. These high-level requests can also specify a desired level of detail, or a maximum size in order to avoid trying to retrieve too much data at one time.
The server API is divided into three categories: dataset management and inquisition, data retrieval, and data creation. The last two types are often combined, for example in the retrieval of a "meta" dataset, composed of multiple individual volumes, that caches it's results into a single super volume for faster access in the future. Similarly, requests that utilize scripting might also cache the results of the script. These results could then be directly accessed at a later time.
All requests to the server must specify action=
with one of the following commands followed by the corresponding arguments. Note that the user agent is used by some requests to determine the default return type (e.g., for listing datasets).
list
Lists datasets hosted by this server.
curl -A visus "http://yourserver.org/mod_visus?action=list"
add_dataset (synonymous with AddDataset)
Adds a dataset to an already-running server.
curl -A visus "http://yourserver.org/mod_visus?action=add_dataset --data-urlencode "xml=<dataset name=\"flame\" permissions=\"public\" url=\"file:///path/to/data/flame/my_flame.idx\"></dataset>"
or alternatively:
curl -A visus "http://yourserver.org/mod_visus?action=add_dataset&name=flame&url=file:///usr/sci/cedmav/data/comp_mat/cracked/idx/cracked.idx"
readdataset (synonymous with read_dataset)
Retrieves the metadata for a given dataset.
curl -A visus "http://atlanta.sci.utah.edu/mod_visus?action=readdataset&dataset=2kbit1"
configure_datasets
Forces the server to reload its internal configuration, ensuring all known datasets are available for retrieval.
curl -A visus "http://atlanta.sci.utah.edu/mod_visus?action=configure_datasets"
Security: Apache authentication
In case you want these requests to be made only by authenticated users or users from a specific network source you can use Apache authentication.
Furthermore some of these commands, such as add_dataset and configure_datasets, might be harmful for your server due to malicious anonymous requests.
On Apache you can configure a set of users that can perform specific requests to the server creating first an AuthUserFile
as following:
htpasswd -c /var/lib/wwwrun/visus/.htpasswd your_username
htpasswd /var/lib/wwwrun/visus/.htpasswd another_username
These commands will also ask you to set a password for each user.
This will create a file .htpasswd
that contains the list of the authorized users and the encrypted passwords.
This file can be used to tell Apache which user can do specific requests. In the following example we added to the httpd.conf
of Apache (version 2.4) some conditions that will require authenticated users only to perform add_dataset and configure_datasets. All the other request (e.g. listing) will be granted to all.
<LocationMatch "/mod_visus"> <If "%{QUERY_STRING} =~ /.*action=AddDataset.*/ || %{QUERY_STRING} =~ /.*action=configure_datasets.*/" > AuthType Basic AuthName "Authentication Required" AuthUserFile "/var/lib/wwwrun/visus/.htpasswd" Require valid-user </If> <Else> Require all granted </Else> SetHandler visus </LocationMatch>
Docker Deployment
A ViSUS server deployed using the ViSUS Docker Deployment is ready to use.
The ViSUS configuration file enables the server to locate datasets and make them accessible to the users (via the ViSUS Viewer).