• Topic
  • Discussion
  • ODS.OdsConfig(Last) -- Owiki? , 2018-04-19 07:08:16 Edit owiki 2018-04-19 03:08:16

    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 in DefaultMailServer INIoption of 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:

    DefaultHost = demo.mydomain.com:1112

    See the URIQA section in the documentation for more details.

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

    ... other plugins..
    LoadPath = /usr/local/lib
    Load1    = plain,im
    Load2    = plain,wikiv
    Load3    = plain,mediawiki
    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, they 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:

    1. OpenLink Data Space (ODS) Framework (ods_framework_dav.vad)
    2. ODS-WebBlog (ods_blog_dav.vad)
    3. ODS-Briefcase (ods_briefcase_dav.vad)
    4. ODS-Feed Manager (ods_feedmanager_dav.vad)
    5. ODS-Wiki (ods_wiki_dav.vad)
    6. ODS-Mail (ods_webmail_dav.vad)
    7. ODS-Bookmark Manager (ods_bookmark_dav.vad)
    8. ODS-Gallery (ods_gallery_dav.vad)
    9. ODS-Community (ods_community_dav.vad)
    10. ODS-Polls (ods_polls_dav.vad)
    11. ODS-Addressbook (ods_addressbook_dav.vad)
    12. ODS-Discussions (ods_discussions_dav.vad)
    VAD Installation

    The next step is to install the VAD packages. With isql, run the following command:

    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 "dav".
    • Click on "Site Settings"
    • Open the "Web Application Configuration" page and enter a Google API key. You can obtain a key by from http://www.google.com/apis/maps/signup.html, and choosing 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 then the map-related features will be disabled.

    • Open the "Mail" settings page.
    • Specify the proper default mail domain, whether to use the default mail server (from the INI) or enter another.
    • Specify the proper 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, or if you are not sure what to use, just leave as it is. Here are the options that change the behavior of the ODS site registration:
      • "Allow WA Default-Site Registrations": if the registration is not allowed only users created by site admin will be able to login.
      • "Verify registration by email" - whether to send a mail to the new users with confirmation 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 the 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 ODS domain is sample.domain) the ODS should be configured via Conductor UI.

    The following describes how to enable an ODS domain :

    • Go to http://host:port/conductor
    • Login as 'dba' and open "WebDAV? & HTTP" then "HTTP Hosts & Directories"
    • Specify the interface address, port to listen and domain like '' (all interfaces), 8888 and 'sample.domain'in the form below the list and click 'Add'
    • Open "System Admin" then "Packages", open the Configure page for "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 selection list to be used as ODS domain.
    • Leave the "Domain registration" option enabled
    • Confirm the changes; the new ODS endpoint will be listed.

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


    • ODS pages

    The ODS pages can be modified by editing the .vspx and.css files in <Virtuoso OpenSource?>/appsrc/ODS-Framework/ and then re-build the ods_dav.vad and re-install it. Alternately, you can install the ods_filesystem.vad package which will put the dynamic web pages in the filesystem and you can edit them as the server is running, 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 the ODS. To do so, the user should go in 'Settings' page and enter the 'Home Page Template Selection'. In the presented text area he/she can edit the home page without any special permissions by ODS administrator.

    Note: The current ODS version of the 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 Conductor via 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 the received mail into the Virtuoso database.

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

    Virtuoso Mail Handler Configuration

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

    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 DSN contains reference to the VOS server SQL port, so this should be replaced if 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,
                    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 changes above.

    Verify Mail Settings

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

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

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

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

    If you see the subject of the mail which was sent in 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 INSTALL document in the <Virtuoso Open Source>/binsrc/maildrop/ directory.

    Setting the VOS SMTP Mail handler on Win32 platforms

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

    To check that open Control Panel, Add or Remove Programs, Add/Remove Windows Components. In the "Internet Information Services" see Details there you must have "SMTP Service" installed, if not check and proceed with windows installation update. Please note that windows installation disk may be asked.

    If SMTP Service is installed then proceed with following steps:

    • Open IIS configuration via Control Panel, Administrative Tools
    • Check the default SMTP Virtual server is running , and if needed add alias or domain. Note the domain name, this will be used in the next 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

      register.bat /register "domain-name"

      where the domain-name is domain that you wish to be served for the purpose (the one from second step)
    • If no error, you should see message like

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

    • Edit the c:\vos\bin\virt_mail.ini and edit 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 Virtuoso OpenSource? server is running and test the SMTP handler installation as follows:
    • Connect with ISQL tool to the VOS database and execute 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;
    1 Rows. -- 0 msec.

    You should see a row with 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 with uncommenting 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