VHOST_DEFINE
define a virtual host or virtual directory
Void DB.DBA.VHOST_DEFINE
(in vhost varchar,
in lhost varchar,
in lpath varchar,
in ppath varchar,
in is_dav boolean,
in is_brws boolean,
in def_page varchar,
in auth_fn varchar,
in realm varchar,
in ppr_fn varchar,
in vsp_user varchar,
in soap_user varchar,
in sec varchar,
in ses_vars boolean,
in soap_opts any,
in auth_opts any,
in opts any,
in is_default_host integer);
Description
VHOST_DEFINE is used to define virtual hosts
and virtual paths on the Virtuoso HTTP server. Effectively this procedure inserts
a row in table DB.DBA.HTTP_PATH Virtuoso
supports both flavours of virtual hosting: IP-based and name-based.
Parameters
vhost –
A string 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.
lhost –
A string 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.
lpath –
A string containing the path component of the
URI for the logical path.
ppath –
A string containing the physical path that the logical
path points to. i.e. a directory or a path to dav collection on server.
is_dav –
An integer. If non-zero, it indicates that
the physical_path points to a collection in DAV
repository. Default value is 0.
is_brws –
An integer. If non-zero, it indicates that the server will
generate a directory listing in case a default page is absent. Default value is 0.
def_page –
A string containing the file name of
the default page. Default value is NULL.
auth_fn –
A string 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.
realm –
A string with the realm to be passed to the
authentication function auth_func. The
default value is NULL.
ppr_fn –
A string containing the fully qualified name of the
Virtuoso/PL stored procedure used for post-processing of the page.
The default values is NULL.
vsp_user –
A string 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.
soap_user –
A string containing a valid SOAP user for SOAP calls.
The default values is NULL.
sec –
Security restrictions (SSL, Digest). The default values is NULL.
ses_vars –
An integer. If non-zero, indicates that session
variables are persistent. The default values is 0.
soap_opts –
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
Optional parameters to the SOAP endpoint.
auth_opts –
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.
opts –
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)
is_default_host –
Return Types
The Return is VOID.
Examples
Define Virtual Hosts
The following command will:
- listen on port 8889 of the interface corresponding with host.foo.com
- maps /appsimple -> /samples/appsimple/
- can get a directory listing
- SQL user which will perform VSP execution is WS
- the persistent session variables flag is on, so can be used in VSPs
SQL> VHOST_DEFINE (vhost=>'www.foo.com:8889',
lhost=>'host.foo.com:8889',
lpath=>'/appsimple',
ppath=>'/samples/appsimple/',
is_brws=>1,
vsp_user=>'WS',
ses_vars=>1);
- listen on standard HTTP port (80)
- maps /appurl -> /samples/appurl/
- can get a directory listing
- SQL user which will perform VSP execution is WS
- the persistent session variables flag is on , can be used in VSPs
SQL> VHOST_DEFINE (vhost=>'www.foo.com',
lhost=>'host.foo.com',
lpath=>'/appurl',
ppath=>'/samples/appurl/',
is_brws=>1,
vsp_user=>'WS',
ses_vars=>1);
- HTTPS server listen on 443 port (will accept HTTP connections via SSL)
- maps /secure -> /samples/appurl/
- SQL user which will perform VSP execution is DBA
- The server certificate is in the ./server.cert file
- and server private key is in the ./server.key file
SQL> VHOST_DEFINE (vhost=>'www.foo.com:443',
lhost=>'host.foo.com:443',
lpath=>'/secure',
ppath=>'/samples/appurl/',
sec=>'SSL',
vsp_user=>'dba',
auth_opts=>vector ('https_key','./server.key','https_cert','./server.cert'));
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/.
The following example demonstrates the use of SOAP options
used in Interop testing.
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'));