Difference between revisions of "ViSUS Server"

Latest revision as of 19:20, 2 November 2017

The ViSUS Server, also known as mod_visus, is an Apache or IIS module that provides simple access to remote multiresolution IDX datasets.

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.

Windows IIS module installation

Build your solution on VisualStudio flagging the CMake option VISUS_BUILD_MODVISUS in Release mode. Check you have a mod_visus.dll in directory ./Release/.

Create a directory /inetpub/wwwroot/visus
Create a file /inetpub/wwwroot/visus/visus.log
Copy your visus.config into /inetpub/wwwroot/visus/.

Edit the visus.config to point to your dataset (see Visus configuration file for reference).

Install module

net stop W3SVC

Uninstall the old mod_visus. From an Administrator Prompt : (Command Prompt / Run as administrator)

%systemroot%\system32\inetsrv\appcmd.exe uninstall module mod_visus

From a Administrator prompt:

%systemroot%\system32\inetsrv\appcmd.exe install module /name:mod_visus /image:C:\path\to\Release\mod_visus.dll

You will get a message like:

GLOBAL MODULE object "mod_visus" added
MODULE object "mod_visus" added

Check and enable ISS modules

Open IIS manager
Double click on modules
Check that mod_visus is there with the right path

Enable mod_visus in Default web site: Default web site/modules/Configure Native modules…. Check mod_visus and press OK.

Configure handler mapping

[Default web site] / [Handler mapping] / /[Actions] / [Add module mapping…]
Request path: *
Module: mod_visus
Executable: leave blanck
Name: mod_visus

Start the server

Checklist before:

DefaultAppPool/.Net Framework version must be ‘.Net framework v4.0.030319’
DefaultAppPool /Managed pipeline mode must be ‘Integrated’.
Default Web site/Manage web site/Advanced settings/Application pool must be ‘DefaultAppPool’
In case you don’t see anywhere “.Net framework v4.0”:

%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_regiis.exe –I

net start W3SVC

Checklist after:

IIS is running
[Application Pool]/ [Default Application pool] is running
[sites] / [Default web site]/is running
Open a browser, type http://localhost/mod_visus?action=list to see the list of datasets available

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=dataset_name&url=file:///path/to/dataset.idx"

readdataset (synonymous with read_dataset)

Retrieves the metadata for a given dataset.

curl -A visus "http://yourserver.org/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://yourserver.org/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.*/ || %{QUERY_STRING} =~ /.*action=add_dataset.*/" >
    AuthType Basic
    AuthName "Authentication Required"
    AuthUserFile "/var/lib/wwwrun/visus/.htpasswd"
    Require valid-user
  </If>

  <Else>
    Require all granted
  </Else>

  SetHandler visus
</LocationMatch>

Usage: how to make authenticated requests

curl -v --user username:password "http://your_server/mod_visus?action=add_dataset&name=dataset_name&url=file:///path/to/dataset.idx"

From a python application you can authenticate as following adding an header to your request:

import urllib2, base64

request = urllib2.Request("http://your_server/mod_visus?action=add_dataset&name=dataset_name&url=file:///path/to/dataset.idx")

username="username" password="password"

base64string = base64.encodestring('%s:%s' % (username, password)).replace('\n', ) request.add_header("Authorization", "Basic %s" % base64string) result = urllib2.urlopen(request)

Some error codes you could get:

HTTP Error 409: Conflict there might be already a dataset with the same name on the server
HTTP Error 401: Unauthorized your credential might be wrong.

Apache Access-Control-Allow-Origin

In case your application executes queries to the visus server from a different host you might need to add to your httpd.conf the following line:

Header set Access-Control-Allow-Origin "*"

Then you can restart apache. If not loaded by default remember to load also the headers module using:

sudo a2enmod headers

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).

Navigation menu