source: trunk/docs/kernel/configuration.rst @ 796

Last change on this file since 796 was 796, checked in by knut, 6 years ago

Added documentation for the [include] section and libPath parameter of main.cfg. Replaced macro RETURN_STRING by RETURN_STRINGL in service_internal_php7.c.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 11.2 KB
Line 
1.. _kernel_config:
2
3ZOO-Kernel configuration
4========================
5
6Main configuration file
7-----------------------
8
9ZOO-Kernel general settings are defined in a configuration file called
10``main.cfg``. This file is stored in the same directory as ZOO-Kernel
11(``/usr/lib/cgi-bin/`` in most cases). It provides usefull metadata information on your ZOO-Kernel installation.     
12
13.. warning::
14  ZOO-Kernel (``/usr/lib/cgi-bin/zoo_loader.cgi``) and its
15  configuration file (``/usr/lib/cgi-bin/main.cfg``) must be in the
16  same directory.
17 
18.. note::
19  Information contained by ``/usr/lib/cgi-bin/main.cfg`` is accessible from WPS Services at runtime, so when *Execute* requests are used.
20
21Default main.cfg
22...............................
23
24An example *main.cfg* file is given here as reference.
25
26.. code-block:: guess
27    :linenos:
28   
29    [headers]
30    X-Powered-By=ZOO@ZOO-Project
31   
32    [main]
33    version=1.0.0
34    encoding=utf-8
35    dataPath=/var/data
36    tmpPath=/var/www/temp
37    cacheDir=/var/www/cache
38    sessPath=/tmp
39    serverAddress=http://localhost/cgi-bin/zoo_loader.cgi
40    lang=fr-FR,ja-JP
41    language=en-US
42    mapserverAddress=http://localhost/cgi-bin/mapserv.cgi
43    msOgcVersion=1.0.0
44    tmpUrl=http:/localhost/temp/
45    cors=false
46   
47    [identification]
48    keywords=t,ZOO-Project, ZOO-Kernel,WPS,GIS
49    title=ZOO-Project demo instance
50    abstract= This is ZOO-Project, the Open WPS platform.
51    accessConstraints=none
52    fees=None
53   
54    [provider]
55    positionName=Developer
56    providerName=GeoLabs SARL
57    addressAdministrativeArea=False
58    addressDeliveryPoint=1280, avenue des Platanes
59    addressCountry=fr
60    phoneVoice=+33467430995
61    addressPostalCode=34970
62    role=Dev
63    providerSite=http://geolabs.fr
64    phoneFacsimile=False
65    addressElectronicMailAddress=gerald@geolabs.fr
66    addressCity=Lattes
67    individualName=Gerald FENOY
68
69
70Main section
71...............................
72
73The main.cfg ``[main]`` section parameters are explained bellow.
74
75 * ``version``: Supported WPS version.
76 * ``encoding``: Default encoding of WPS Responses.
77 * ``dataPath``: Path to the directory where data files are stored (used to store mapfiles and data when MapServer support is activated).
78 * ``tmpPath``: Path to the directory where temporary files are stored (such as *ExecuteResponse* when *storeExecuteResponse* is set to true).
79 * ``tmpUrl``: URL to access the temporary files directory (cf. ``tmpPath``).
80 * ``cacheDir``: Path to  the directory where cached request files [#f1]_ are stored (optional).
81 * ``serverAddress``: URL to the ZOO-Kernel instance.
82 * ``mapservAddress``: URL to the MapServer instance (optional).
83 * ``msOgcVersion``: Version of all supported OGC Web Services output [#f2]_
84   (optional).
85 * ``lang``: Supported natural languages separated by a coma (the first is the default one),
86 * ``cors``: Define if the ZOO-Kernel should support `Cross-Origin
87   Resource Sharing <https://www.w3.org/TR/cors/>`__. If this
88   parameter is not defined, then the ZOO-Kernel won't support CORS.
89 * ``servicePath``: Define a specific location to search for services
90   rather than using the ZOO-Kernel directory. If this parameter is
91   not defined, then the ZOO-Kernel will search for services using its
92   directory.
93 * ``libPath``: (Optional) Path to a directory where the ZOO-kernel should search for
94   service providers, e.g., shared libraries with service implementations
95   (the ``serviceProvider`` parameter in the service configuration (.zcfg) file).   
96
97.. warning::
98  The ``libPath`` parameter is currently only recognized by services implemented
99  in C/C++ or PHP, and may be moved to another section in future versions.
100 
101In case you have activated the MapServer support, please refer to
102:ref:`this specific section <kernel-mapserver-main.cfg>`.
103
104
105Identification and Provider
106..........................................
107
108The ``[identification]`` and ``[provider]`` sections are not ZOO-Project
109specific. They provide OGC metadata [#f3]_ and should be set according
110to the `XML Schema Document
111<http://schemas.opengis.net/ows/1.1.0/ows19115subset.xsd>`__ which
112encodes the parts of ISO 19115 used by the common
113*ServiceIdentification* and *ServiceProvider* sections of the
114*GetCapabilities* operation response, known as the service metadata
115XML document.
116
117Details of the common OWS 1.1.0 *ServiceIdentification* section can be
118found in this `XML Schema Document
119<http://schemas.opengis.net/ows/1.1.0/owsServiceIdentification.xsd>`__.
120
121Details of the common OWS 1.1.0 *ServiceProvider* section can be
122found in this `XML Schema Document
123<http://schemas.opengis.net/ows/1.1.0/owsServiceProvider.xsd>`__.
124
125
126Additional sections
127--------------------------------
128
129Headers section
130...............................
131
132The ``[headers]`` section can be set in order to define a specific HTTP
133Response header, which will be used for every response. As an example,
134you can check http://zoo-project.org using *curl* command line tool
135and notice the specific header *X-Powered-By: Zoo-Project@Trac*.
136
137In case you want to allow CORS support for POST requests coming from
138``myhost.net``, then you should define the following minimal
139parameters in this section:
140
141.. code-block:: guess
142    :linenos:
143   
144    Access-Control-Allow-Origin=myhost.net
145    Access-Control-Allow-Methods=POST
146    Access-Control-Allow-Headers=content-type
147
148
149env section
150...............................
151
152The ``[env]`` section can be used to store specific environment
153variables to be set prior the loading of *Services Provider* and Service execution.
154
155A typical example is when a Service requires the access to a X server
156running on *framebuffer*, which takes to set the DISPLAY environnement
157variable, as follow:
158
159.. code-block:: guess
160    :linenos:
161   
162    [env]
163    DISPLAY=:1
164
165In case you have activated the OTB support, please refer to :ref:`this
166specific section <kernel-orfeotoolbox-main.cfg>`.
167
168lenv section
169...............................
170
171The ``lenv`` section is used by the ZOO-Kernel to store runtime informations
172before the execution of a WPS service, it contains the following
173parameters:
174
175 * ``sid`` (r): The WPS Service unique identifier,
176 * ``status`` (rw): The current progress value ( a value between 0 and
177   100 in percent (**%**) ),
178 * ``cwd`` (r): The current working directory of ZOO-Kernel,
179 * ``message`` (rw): An error message used when ``SERVICE_FAILED`` is returned (optional),
180 * ``cookie`` (rw): The cookie to be returned to the client (for
181   example for authentication purpose).
182 * ``file.pid`` (r): The file used by the ZOO-Kernel to store process identifier.
183 * ``file.sid`` (r): The file used by the ZOO-Kernel to store service identifier.
184 * ``file.responseInit`` (r): The file used by the ZOO-Kernel to store
185   the initial (then final) WPS response.
186 * ``file.responseFinal`` (r): The file used by the ZOO-Kernel to
187   temporary store the final WPS response.
188
189renv section
190...............................
191
192The ``renv`` section is automatically created by the ZOO-Kernel before
193the execution of a WPS service, it contains all the environment
194variables available at runtime (so including the header fields in case
195it is used through http, refer to [https://tools.ietf.org/html/rfc3875
196rfc3875] for more details).
197
198
199senv section
200...............................
201
202The ``senv`` section can be used to store sessions information on the
203server side. Such information can then be accessed automatically from
204the Service if the server is requested using a valid cookie (as
205defined in ``lenv`` section). ZOO-Kernel will store the values set in the
206``senv`` maps on disk, load it and dynamically replace its content to
207the one in the ``main.cfg``. The ``senv`` section must contain the
208following parameter at least:
209
210 * ``XXX``: The session unique identifier where ``XXX`` is the name
211   included in the cookie which is returned.
212
213.. _cookie_example:
214
215For instance, adding the following in the Service source code  :
216
217.. code:: python
218   
219    conf["lenv"]["cookie"]="XXX=XXX1000000; path=/"
220    conf["senv"]={"XXX": "XXX1000000","login": "demoUser"}
221
222means that ZOO-Kernel will create a file named ``sess_XXX1000000.cfg``
223in the ``cacheDir`` directory, and will return the specified cookie to the client. Each time the client will
224request ZOO-Kernel using this cookie, it will automatically load the
225value stored before the Service execution.
226
227.. _zoo_activate_db_backend:
228
229Database section
230...............................
231
232The database section allows to configure the
233:ref:`ZOO-Kernel optional database support <zoo_install_db_backend>`.
234
235.. code-block:: guess
236
237        [database]
238        dbname=zoo_project
239        port=5432
240        user=username
241        host=127.0.0.1
242        type=PG
243        schema=public
244
245This will generate strings to be passed to GDAL to connect the
246database server:
247
248.. code-block:: guess
249   
250    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
251
252
253With the previous database section, it will give the following:
254
255.. code-block:: guess
256
257    PG:"dbname=zoo_project host=127.0.0.1 port=5432 user=username"
258
259Please refer to this `section <zoo_create_db_backend>`_ to learn how
260to setup the database.
261
262Include section
263...............................
264
265The ``[include]`` section (optional) lists explicitely a set of service configuration files
266the the ZOO-Kernel should parse, e.g.,
267
268
269.. code-block:: guess
270    :linenos:
271   
272    [include]
273    servicename1 = /my/service/repository/service1.zcfg
274    servicename2 = /my/service/repository/service2.zcfg
275
276The ``[include]`` section may be used to control which services are exposed to particular user groups.
277While service configuration files (.zcfg) may be located in a common repository or in arbitrary folders,
278main.cfg files at different URLs may include different subsets of services.
279
280When the ZOO-Kernel handles a request, it will first check if there is an ``[include]``
281section in main.cfg and then search for other .zcfg files in the current working directory (CWD) and
282subdirectories. If an included service happens to be located in a CWD (sub)directory,
283it will be published by its name in the ``[include]`` section. For example, the service
284``/[CWD]/name/space/myService.zcfg``
285would normally be published as name.space.myService, but if it is listed in the ``[include]`` section
286it will be published simply as myService:
287
288.. code-block:: guess
289    :linenos:
290   
291    [include]
292    myService =  /[CWD]/name/space/myService.zcfg
293
294On the other hand, with
295
296.. code-block:: guess
297    :linenos:
298   
299    [include]
300    myService =  /some/other/dir/myService.zcfg
301
302there would be two distinct services published as myService and name.space.myService, respectively,
303with two different zcfg files.
304
305.. note::
306  As currently implemented, the ZOO-Kernel searches the CWD for the library files of
307  included services if the ``libPath`` parameter is not set.
308
309     
310.. rubric:: Footnotes
311
312.. [#f1] If GET requests are passed through ``xlink:href`` to the ZOO-Kernel , the latter will execute the request the first time and store the result  on disk. The next time the same request is executed, the cached file will be used and this will make your process run much faster. If ``cachedir`` was not specified in the ``main.cfg`` then the ``tmpPath`` value will be used.
313.. [#f2] Usefull when the :ref:`kernel-mapserver` is activated (available since ZOO-Project version 1.3.0).
314.. [#f3] ZOO-Kernel and MapServer are sharing the same metadata for OGC Web Services if the :ref:`kernel-mapserver` is activated.
315
316   
Note: See TracBrowser for help on using the repository browser.

Search

ZOO Sponsors

http://www.zoo-project.org/trac/chrome/site/img/geolabs-logo.pnghttp://www.zoo-project.org/trac/chrome/site/img/neogeo-logo.png http://www.zoo-project.org/trac/chrome/site/img/apptech-logo.png http://www.zoo-project.org/trac/chrome/site/img/3liz-logo.png http://www.zoo-project.org/trac/chrome/site/img/gateway-logo.png

Become a sponsor !

Knowledge partners

http://www.zoo-project.org/trac/chrome/site/img/ocu-logo.png http://www.zoo-project.org/trac/chrome/site/img/gucas-logo.png http://www.zoo-project.org/trac/chrome/site/img/polimi-logo.png http://www.zoo-project.org/trac/chrome/site/img/fem-logo.png http://www.zoo-project.org/trac/chrome/site/img/supsi-logo.png http://www.zoo-project.org/trac/chrome/site/img/cumtb-logo.png

Become a knowledge partner

Related links

http://zoo-project.org/img/ogclogo.png http://zoo-project.org/img/osgeologo.png