OpenLink Data Spaces (ODS) Quick Start

Configuring ODS

ODS is now delivered as part of the Virtuoso Open Source 5.0 edition. This page provides instructions on installation of the ODS suite of Data Space applications.

Please note that ODS is preinstalled into the Virtuoso Demo Database. Thus, you do not need to perform the installation steps below if working with a Virtuoso 5.0 (or higher) demonstration database.

Configuration Parameters

ODS depends on certain parameters in the Virtuoso Database Initialization File (INI file), e.g. "demo.ini" for the demonstration database. The settings in this file are appropriate for most installations. Thus, prior to starting the Virtuoso server, you need to verify that the following parameters in the INI file are set:

HTTP Server is enabled ('HTTPServer' section) .
The default mail server is properly specified by the DefaultMailServer INI option in the 'HTTPServer' section. This must point to a valid SMTP server for outgoing mail.
The URIQA section must have a proper 'DefaultHost' setting and must contain the name and http port of the HTTP listener. This name must be valid across the network where ODS will be used. This may require you to have a CNAME or similar entry in DNS for the service.

For example:

[URIQA]
DefaultHost = demo.mydomain.com:1112

See the URIQA section in the documentation for more details.

The ImageMagick, Wikiv, CreoleWiki, and MediaWiki plugins are enabled via the following entries in the "[Plugins]" section:

{{{Load5    = plain,creolewiki
... other plugins ...

Locate and install the VAD packages

VAD Packages

Once you have verified the server settings, the next step is to install the VAD packages.

For binary distributions and the tree made by make install, packages are located in the share/virtuoso/vad directory under the installation root. If you are using the demo database, the packages are preinstalled.

The ODS VAD packages for this release include:

VAD Installation

The next step is to install the VAD packages. Run the following command with isql:

SQL> VAD_INSTALL('<path of the VAD file>',0);

Install the files in the order of the above listing. The web pages of the packages will go into the server's WebDAV repository.

DNS Settings

If you wish to offer virtual host names for applications, as in myblog.example.com, then the DNS has to be set up to direct *.example.com to the host where Virtuoso is running. If users will not choose virtual host names for their applications, this step can be skipped.

Configure ODS

The larger part of configuration is performed through the browser:

Enter the URL http:[host]:[port]/ods where the host and port are the server and port your Virtuoso instance is running on. (e.g. http://localhost:8890/ods/).
Login as "dav". The default password is also "dav".
Click on "Site Settings."
Open the "Web Application Configuration" page and enter a Google API key. You can obtain a key from http://www.google.com/apis/maps/signup.html . Just choose the appropriate Geocoder service. Note that not all Geocoder services return addresses for non-US countries.
Save the changes and return to the "Site Settings" via the link at the top.

You can skip these steps, but the map-related features will be disabled.

Open the "Mail" settings page.
Specify the default mail domain. Specify whether to use the default mail server (from the INI) or enter another.
Specify the ODS admin mail address and save the settings.
Press the "Test" button to verify that the mail settings actually work.
Return to the "Site Settings" page.
Enter the "Member Registration Settings" page.
Select the desired registration scheme from the options. f you are not sure what to use, leave it as it is. Here are the options that change the behavior of the ODS site registration:

"Allow WA Default-Site Registrations": If registration is not allowed. only users created by a site admin will be able to login.
"Verify registration by email" - Specifices whether to send a confirmation mail to new users or create the account immediately.

ODS is now ready for use.

Note: If you disable the default site registration, then in addition to the above, the ODS admin will need to create user accounts for site members.

Configuring the ODS domain(s)

In order to allow ODS users to create their own sub-domains (e.g. user.sample.domain, where the ODS domain is sample.domain), the ODS should be configured via the Conductor UI.

The following steps describe how you may enable an ODS domain :

Go to http://host:port/conductor.
Login as 'dba' and open "WebDAV & HTTP"=> "HTTP Hosts & Directories."
Specify the interface address, listen port, and domain like '0.0.0.0' (all interfaces), 8888, and 'sample.domain' in the form below the list. Then, click 'Add.'
Open "System Admin"=>"Packages." Then, open the Configure page for the "Framework" package.
Select "Create New Endpoint" link; the new ODS endpoint form should be shown.
You can specify either "Endpoint prefix" or "Virtual directory" or both to enable the domain from the selection list to be used as an ODS domain.
Leave the "Domain registration" option enabled.
Confirm the changes; the new ODS endpoint will be listed.

After performing the above steps, the new domain will be selectable when choosing a virtual host name for new application instances.

Customization

ODS pages

The ODS pages can be modified by editing the *.vspx and *.css files in <Virtuoso OpenSource>/appsrc/ODS-Framework/ and then re-building the ods_dav.vad and re-installing it. Alternately, you can install the ods_filesystem.vad package which will put the dynamic web pages in the filesystem. You can edit the pages while the server is running, just as you would edit any dynamic web pages under PHP or similar.

User's home

The users in ODS may wish to change the look and feel of their own home pages in ODS. To do so, the user should go to the 'Settings' page and enter the 'Home Page Template Selection'. In the presented text area, he or she can edit the home page without special permissions from the ODS administrator.

Note: The current version of ODS contains one 'default' home page template, which can serve as a basis for customization.

Adding users with Conductor

IMPORTANT: Below are instructions for adding new user accounts, if registrations are disabled.

This can be performed in the Conductor (pre-installed on the Demo Database):

Open the Conductor via a browser at http://host:port/conductor (e.g. http://localhost:8890/conductor/).
Login as 'dba'.
Go to "System Admin" and the "User Accounts" tab.
Open the "Create New Account" page.
Enter the requested information and check "Allow DAV Logins".
Repeat the previous step for every member of ODS.
From the Conductor's left-hand menu, click on the "Data Space" or "Web Applications" link in the Conductor to commence using your Data Space applications. (This will take you to http://localhost:8890/ods/ .)

Configuring the Virtuoso mail handler

Virtuoso provides a local mail delivery program (virt_mail) for SMTP servers. This program is used to store received mail into the Virtuoso database.

The following instructions are applicable to UNIX systems using sendmail as a mail server.

Virtuoso Mail Handler Configuration

Copy virt_mail to /usr/bin/virt_mail.
Copy /binsrc/maildrop/odbc_mail.default.ini to /etc/odbc_mail.ini.
Edit /etc/odbc_mail.ini and change the login settings to match your current database installation:

[Options]
DSN = DSN=Virtuoso; HOST=localhost:1111;UID=dba;PWD=dba
;MaxMessageSize = 2097152
Verify = DB.DBA.WA_MAIL_VALIDATE ('$local')
Deliver = DB.DBA.WA_NEW_MAIL('$1', $message)

(You can probably leave the rest of the odbc_mail.ini alone.)

Note that the DSN contains reference to the VOS server SQL port. This should be modified, if a non-default SQL port (1111) is used.

Sendmail program configuration

Replace the default local mailer in your sendmail.cf:

...
#Mlocal,        P=/usr/bin/procmail, F=lsDFMAw5:/|@qSPfhn9, S=EnvFromL/HdrFromL, R=EnvToL/HdrToL,
#               T=DNS/RFC822/X-Unix,
#               A=procmail -t -Y -a $h -d $u
Mlocal,         P=/usr/bin/virt_mail, F=lsDFMA5:/|@qSPhn9, S=10/30, R=20/40,
                T=DNS/RFC822/X-Unix,
                A=virt_mail -c /etc/odbc_mail.ini -l $u -h $h -s $g
...

IMPORTANT: Make sure that ODS packages are installed prior to making the above changes.

Verify Mail Settings

Send an e-mail to the 'dav' user account:

bash$ mail dav@<domain>
Subject: virt-mail-test
.
Cc:

Using the ISQL tool, check the mailbox of the 'dav' user account:

SQL> select mm_subj from mail_message where mm_own = 'dav';
MM_SUBJ
VARCHAR
_______________________________________________________________________________

virt-mail-test

If you see the subject of the mail which was sent in the previous step, then the handler works correctly. Otherwise, you should check the log of the sendmail program.

Other SMTP Servers

For the other mail server programs, please consult the INSTALL document in the <Virtuoso Open Source>/binsrc/maildrop/ directory.

Setting the VOS SMTP Mail handler on Win32 platforms

Before starting, make sure that STMP services for Internet Information Services (IIS) are installed on your windows box.

To check, open Control Panel

>Add or Remove Programs

>Add/Remove Windows Components. In "Internet Information Services," review Details. There, you must have "SMTP Service" installed. If not check the service and proceed with a windows installation update. Please note that the windows installation disk may be requested.

If SMTP Service is installed, proceed with the following steps:

Open IIS configuration via Control Panel=>Administrative Tools.
Check to see that the default SMTP Virtual server is running, and if needed, add an alias or domain. Note the domain name. This will be used in future steps.
Open a command prompt (CMD).
Go to the VOS binary distribution (c:\vos for example) in the c:\vos\bin directory.
Make sure register.bat, smtpreg.vbs, and virt_mail.ini are in place. If not, download the ZIP (attached) and unpack in this directory.
Run the following command:
```
   register.bat /register "domain-name"
```
Here, the domain-name is the domain that you wish to be served.

If no error occurs, you should see a message like:


   assigning priority (0 of 32767)
   registered OpenLink MailDrop
   set priority Command to c:\vos\bin\virt_mail.exe

Open c:\vos\bin\virt_mail.ini and edit the HOST address and port to match your Virtuoso OpenSource server in following line :

   DSN = DSN=Virtuoso; HOST=localhost:1112;UID=dba;PWD=dba

Make sure the Virtuoso OpenSource server is running, and test the SMTP handler installation as follows:

Connect with ISQL to the VOS database and execute the following commands:

SQL> smtp_send ('localhost:25', 'dba@testdomain', 'dba@testdomain', 'Subject: test\r\n\r\ntest');

Done. -- 26 msec.
SQL> select MM_SUBJ from mail_message;
MM_SUBJ
VARCHAR
_______________________________________________________________________________

test

1 Rows. -- 0 msec.
SQL>

You should see a row with the text "test" in the result. Please note that "testdomain" should be replaced by your domain (see above).

If something is broken, you can turn on logging in virt-mail.ini by uncommenting the MailDebug setting.
If all is ok, then change the Verify and Deliver options in virt_mail.ini to:

Verify = DB.DBA.WA_MAIL_VALIDATE ('$local')
Deliver = DB.DBA.WA_NEW_MAIL('$1', $message)

The STMP mail handler is ready for use with VOS ODS applications.

Referenced by...