<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<refentry id="fn_vhost_define">
  <refmeta>
    <refentrytitle>VHOST_DEFINE</refentrytitle>
    <refmiscinfo>ws</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>VHOST_DEFINE</refname>
    <refpurpose>define a virtual host or virtual directory</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <funcsynopsis id="fsyn_vhost_define">
      <funcprototype id="fproto_vhost_define">
        <funcdef>Void DB.DBA.<function>VHOST_DEFINE</function></funcdef>
	<paramdef>in <parameter>vhost</parameter> varchar</paramdef>
	<paramdef>in <parameter>lhost</parameter> varchar</paramdef>
	<paramdef>in <parameter>lpath</parameter> varchar</paramdef>
	<paramdef>in <parameter>ppath</parameter> varchar</paramdef>
	<paramdef>in <parameter>is_dav</parameter> boolean</paramdef>
	<paramdef>in <parameter>is_brws</parameter> boolean</paramdef>
	<paramdef>in <parameter>def_page</parameter> varchar</paramdef>
	<paramdef>in <parameter>auth_fn</parameter> varchar</paramdef>
	<paramdef>in <parameter>realm</parameter> varchar</paramdef>
	<paramdef>in <parameter>ppr_fn</parameter> varchar</paramdef>
	<paramdef>in <parameter>vsp_user</parameter> varchar</paramdef>
	<paramdef>in <parameter>soap_user</parameter> varchar</paramdef>
	<paramdef>in <parameter>sec</parameter> varchar</paramdef>
	<paramdef>in <parameter>ses_vars</parameter> boolean</paramdef>
	<paramdef>in <parameter>soap_opts</parameter> any</paramdef>
	<paramdef>in <parameter>auth_opts</parameter> any</paramdef>
	<paramdef>in <parameter>opts</parameter> any</paramdef>
	<paramdef>in <parameter>is_default_host</parameter> integer</paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>
  <refsect1 id="desc_vhost_define"><title>Description</title>
    <para><function>VHOST_DEFINE</function> is used to define virtual hosts 
    and virtual paths on the Virtuoso HTTP server. Effectively this procedure inserts 
    a row in table <computeroutput>DB.DBA.HTTP_PATH</computeroutput> Virtuoso 
    supports both flavours of virtual hosting: IP-based and name-based.</para>
    </refsect1>

  <refsect1 id="params_vhost_define"><title>Parameters</title>
    <refsect2><title><parameter>vhost</parameter></title>
      <para>A <type>string</type> containing the virtual host name that the
browser presents as Host: entry in the request headers. i.e. Name-based virtual hosting.
The default value is taken from the Virtuoso INI file.</para>
    </refsect2>
    <refsect2><title><parameter>lhost</parameter></title>
      <para>A <type>string</type> containing the  address of the network
interface the Virtuoso HTTP server uses to listen and accept connections.
The default value is taken from the Virtuoso INI file.</para>
    </refsect2>
    <refsect2><title><parameter>lpath</parameter></title>
      <para>A <type>string</type> containing the path component of the
URI for the logical path.</para>
    </refsect2>
    <refsect2><title><parameter>ppath</parameter></title>
      <para>A string containing the physical path that the logical
path points to. i.e. a directory or a path to dav collection on server.</para>
    </refsect2>
    <refsect2><title><parameter>is_dav</parameter></title>
      <para>An <type>integer</type>. If non-zero, it indicates that
the <parameter>physical_path</parameter> points to a collection in DAV
repository.  Default value is 0.</para>
    </refsect2>
    <refsect2><title><parameter>is_brws</parameter></title>
      <para>An <type>integer</type>. If non-zero, it indicates that the server will
generate a directory listing in case a default page is absent.  Default value is 0.</para>
    </refsect2>
    <refsect2><title><parameter>def_page</parameter></title>
      <para>A <type>string</type> containing the file name of
the default page.  Default value is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>auth_fn</parameter></title>
      <para>A <type>string</type> that contains the fully qualified Virtuoso/PL
procedure name of authentication hook function that will check and perform
authentication for this virtual host or directory. If NULL, Virtuoso will not
attempt authentication.  The default value is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>realm</parameter></title>
      <para>A <type>string</type> with the realm to be passed to the
authentication function <parameter>auth_func</parameter>.  The
default value is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>ppr_fn</parameter></title>
      <para>A <type>string</type> containing the fully qualified name of the
Virtuoso/PL stored procedure used for post-processing of the page.
The default values is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>vsp_user</parameter></title>
      <para>A <type>string</type> containing a valid DB user name.  The VSP pages
contained in the virtual directory shall be run with the grants effective for
this user at time of execution.  The default values is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>soap_user</parameter></title>
      <para>A <type>string</type> containing a valid SOAP user for SOAP calls.
The default values is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>sec</parameter></title>
      <para>Security restrictions (SSL, Digest).  The default values is NULL.</para>
    </refsect2>
    <refsect2><title><parameter>ses_vars</parameter></title>
      <para>An <type>integer</type>. If non-zero, indicates that session
variables are persistent.  The default values is 0.</para>
    </refsect2>
    <refsect2><title><parameter>soap_opts</parameter></title>
      <para>Options for SOAP service.  The default values is NULL.
      The SOAP options are name-value pairs contained in a vector:
      i.e. vector ('name1', 'value1', ....).  The SOAP server accepts the
      optional parameters as described in <link linkend="soapoptions">Optional parameters to the SOAP endpoint</link>.</para>

    </refsect2>
    <refsect2><title><parameter>auth_opts</parameter></title>
      <para>Options for the authentication hook and HTTPS listen hosts.  The default values is NULL.
      If the sec_method (security method) defined as 'SSL' the following auth_options must be supplied:
      https_cert - HTTPS server certificate file path, https_key - HTTPS server private key file path.
      In addition to check X509 certificate of clients, the https_cv option with path to the file containing trusted certificate authorities must be supplied and https_cv_depth - integer to set depth of client certificate checking.
      </para>
    </refsect2>
    <refsect2><title><parameter>opts</parameter></title>
      <para>
      Extension options to the virtual directory itself. The default is NULL.
      When it's used the value MUST be a vector of name and value pairs. 
      The supported extension options are: 
      "noinherit" - denotes that all paths requested and matched this directory will be 
      treated only as physical location (no expansion, no inheritance). It may used with a single page to the directory mapping. 
      "xml_templates" - This denotes that .xml files under that directory and indirect children will be treated as a XML Template files (i.e. they will be executed).
      "executable" - this flag is used to override the execution permissions of the active pages stored within WebDAV repository (i.e. if it's set the active pages will be executed no matter what are their execution permission flag)
      </para>
    </refsect2>
    <refsect2><title><parameter>is_default_host</parameter></title>
      <para>
      </para>
    </refsect2>
  </refsect1>
  <refsect1 id="ret_vhost_define"><title>Return Types</title><para>The Return is VOID.</para></refsect1>
<!--
  <refsect1 id="errors_vhost_define"><title>Errors</title>
    <table><title>Errors signalled by</title>
      <tgroup cols="4">
	<thead><row><entry>SQLSTATE</entry><entry>ERROR CODE</entry><entry>ERROR TEXT</entry><entry>DESCRIPTION</entry></row></thead>
	<tbody>
	  <row>
	    <entry><errorcode></errorcode></entry>
	    <entry><errorcode></errorcode></entry>
	    <entry><errorname></errorname></entry>
	    <entry></entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>
-->
  <refsect1 id="examples_vhost_define"><title>Examples</title>
    <example id="ex_vhost_define"><title>Define Virtual Hosts</title>
    <para>The following command will:</para>
    <simplelist>
      <member>listen on port 8889 of the interface corresponding with host.foo.com</member>
      <member>maps /appsimple -&gt; /samples/appsimple/</member>
      <member>can get a directory listing</member>
      <member>SQL user which will perform VSP execution is WS</member>
      <member>the persistent session variables flag is on, so can be used in VSPs</member>
    </simplelist>
<programlisting>
SQL&gt; VHOST_DEFINE (vhost=&gt;'www.foo.com:8889',
  lhost=&gt;'host.foo.com:8889',
  lpath=&gt;'/appsimple',
  ppath=&gt;'/samples/appsimple/',
  is_brws=&gt;1,
  vsp_user=&gt;'WS',
  ses_vars=&gt;1);
  </programlisting>
  <simplelist>
    <member>listen on standard HTTP port (80)</member>
    <member>maps /appurl -&gt; /samples/appurl/</member>
    <member>can get a directory listing</member>
    <member>SQL user which will perform VSP execution is WS</member>
    <member>the persistent session variables flag is on , can be used in VSPs</member>
  </simplelist>
<programlisting>
SQL&gt; VHOST_DEFINE (vhost=&gt;'www.foo.com',
  lhost=&gt;'host.foo.com',
  lpath=&gt;'/appurl',
  ppath=&gt;'/samples/appurl/',
  is_brws=&gt;1,
  vsp_user=&gt;'WS',
  ses_vars=&gt;1);
  </programlisting>
  <simplelist>
    <member>HTTPS server listen on 443 port (will accept HTTP connections via SSL)</member>
    <member>maps /secure -&gt; /samples/appurl/</member>
    <member>SQL user which will perform VSP execution is DBA</member>
    <member>The server certificate is in the ./server.cert file</member>
    <member>and server private key is in the ./server.key file</member>
  </simplelist>
<programlisting>
SQL&gt; VHOST_DEFINE (vhost=&gt;'www.foo.com:443',
  lhost=&gt;'host.foo.com:443',
  lpath=&gt;'/secure',
  ppath=&gt;'/samples/appurl/',
  sec=&gt;'SSL',
  vsp_user=&gt;'dba',
  auth_opts=&gt;vector ('https_key','./server.key','https_cert','./server.cert'));
</programlisting>
  <para>
If a browser points to the URL http://www.foo.com/ it will get a directory listing of /samples/appurl/, or
if a browser points to http://www.foo.com:8889/ it will will get a directory listing of /samples/appsimple/.
</para>

<para>The following example demonstrates the use of SOAP options
used in <link linkend="soapwsdlinterop">Interop</link> testing.</para>
<programlisting><![CDATA[
  VHOST_DEFINE (lpath=>'/Interop',
                ppath=>'/SOAP/',
		soap_user=>'INTEROP',
		soap_opts=> vector(
			       'SchemaNS','http://soapinterop.org/xsd',
			       'Namespace','http://soapinterop.org/',
			       'MethodInSoapAction','no',
			       'ServiceName', 'InteropTests',
			       'HeaderNS', 'http://soapinterop.org/echoheader/',
			       'CR-escape', 'yes'));]]></programlisting>
    </example>
<para>Example that covers TLS mutual authentication and custom re-write rules handlers for 403 and 401 
	HTTP Status responses:</para>
<programlisting><![CDATA[
DB.DBA.VHOST_DEFINE (
      lhost=>':443',
      vhost=>'example.com',
      lpath=>'/DAV',
      ppath=>'/DAV/',
      is_dav=>1,
      vsp_user=>'dba',
      ses_vars=>0,
      opts=>vector ('url_rewrite', 'rdf_sink_rule_list', '401_page', 
'demo/authenticate.vsp', '403_page', 'demo/authenticate.vsp'),
      sec=>'SSL',
      auth_opts=>vector ('https_cert', 'db:john_smith_CA2', 'https_key', 
'db:john_smith_CA2', 'https_verify', 3, 'https_cv_depth', 10),
      is_default_host=>0
]]></programlisting>    
  </refsect1>
  <refsect1 id="seealso_vhost_define"><title>See Also</title>
    <para>Chapter <link linkend="webandxml">Virtuoso Web and XML Support</link> in the Virtuoso Manual for discussion on this topic. <link linkend="fn_vhost_remove">vhost_remove</link>.</para>
  </refsect1>
</refentry>