source: trunk/docs/kernel/configuration.rst

Last change on this file was 950, checked in by djay, 11 months ago

Add documentation for the oas.cfg file and clean it a bit.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 18.5 KB
Line 
1
2.. _kernel_config:
3
4ZOO-Kernel configuration
5========================
6
7Main configuration file
8-----------------------
9
10ZOO-Kernel general settings are defined in a configuration file called
11``main.cfg``. This file is stored in the same directory as ZOO-Kernel
12(``/usr/lib/cgi-bin/`` in most cases). It provides usefull metadata information on your ZOO-Kernel installation.     
13
14.. warning::
15  ZOO-Kernel (``/usr/lib/cgi-bin/zoo_loader.cgi``) and its
16  configuration file (``/usr/lib/cgi-bin/main.cfg``) must be in the
17  same directory.
18 
19.. note::
20  Information contained by ``/usr/lib/cgi-bin/main.cfg`` is accessible from WPS Services at runtime, so when *Execute* requests are used.
21
22Default main.cfg
23...............................
24
25An example *main.cfg* file is given here as reference.
26
27.. code-block:: guess
28    :linenos:
29   
30    [headers]
31    X-Powered-By=ZOO@ZOO-Project
32   
33    [main]
34    version=1.0.0
35    encoding=utf-8
36    dataPath=/var/data
37    tmpPath=/var/www/temp
38    cacheDir=/var/www/cache
39    sessPath=/tmp
40    serverAddress=http://localhost/cgi-bin/zoo_loader.cgi
41    lang=fr-FR,ja-JP
42    language=en-US
43    mapserverAddress=http://localhost/cgi-bin/mapserv.cgi
44    msOgcVersion=1.0.0
45    tmpUrl=http:/localhost/temp/
46    cors=false
47   
48    [identification]
49    keywords=t,ZOO-Project, ZOO-Kernel,WPS,GIS
50    title=ZOO-Project demo instance
51    abstract= This is ZOO-Project, the Open WPS platform.
52    accessConstraints=none
53    fees=None
54   
55    [provider]
56    positionName=Developer
57    providerName=GeoLabs SARL
58    addressAdministrativeArea=False
59    addressDeliveryPoint=1280, avenue des Platanes
60    addressCountry=fr
61    phoneVoice=+33467430995
62    addressPostalCode=34970
63    role=Dev
64    providerSite=http://geolabs.fr
65    phoneFacsimile=False
66    addressElectronicMailAddress=gerald@geolabs.fr
67    addressCity=Lattes
68    individualName=Gerald FENOY
69
70
71Main section
72...............................
73
74The main.cfg ``[main]`` section parameters are explained bellow.
75
76 * ``version``: Supported WPS version.
77 * ``encoding``: Default encoding of WPS Responses.
78 * ``dataPath``: Path to the directory where data files are stored (used to store mapfiles and data when MapServer support is activated).
79 * ``tmpPath``: Path to the directory where temporary files are stored (such as *ExecuteResponse* when *storeExecuteResponse* is set to true).
80 * ``tmpUrl``: URL to access the temporary files directory (cf. ``tmpPath``).
81 * ``cacheDir``: Path to  the directory where cached request files [#f1]_ are stored (optional).
82 * ``serverAddress``: URL to the ZOO-Kernel instance.
83 * ``mapservAddress``: URL to the MapServer instance (optional).
84 * ``msOgcVersion``: Version of all supported OGC Web Services output [#f2]_
85   (optional).
86 * ``lang``: Supported natural languages separated by a coma (the first is the default one),
87 * ``cors``: Define if the ZOO-Kernel should support `Cross-Origin
88   Resource Sharing <https://www.w3.org/TR/cors/>`__. If this
89   parameter is not defined, then the ZOO-Kernel won't support CORS.
90 * ``servicePath``: Define a specific location to search for services
91   rather than using the ZOO-Kernel directory. If this parameter is
92   not defined, then the ZOO-Kernel will search for services using its
93   directory.
94 * ``libPath``: (Optional) Path to a directory where the ZOO-kernel should search for
95   service providers, e.g., shared libraries with service implementations
96   (the ``serviceProvider`` parameter in the service configuration (.zcfg) file).   
97 * ``memory``: (Optional) can take the value ``load`` to ensure that
98   the value field of the inputs data will be filled by the ZOO-Kernel
99   or ``protected`` to have only the ``cache_file`` filled.
100 * ``handleText``: (Optional) set it to ``true`` to get your Complex data
101   nodes containing text not requiring a single CDATA node. Be aware
102   that in case you use any HTML or XML there, you will then need to
103   rebuild the string to get the original format of the text from your
104   service code. In case you do not add handleText or set its value to
105   true, you will simply need to use the value as it was provided in
106   a single CDATA node provided in the Execute request.
107
108.. warning::
109  The ``libPath`` parameter is currently only recognized by services implemented
110  in C/C++ or PHP, and may be moved to another section in future versions.
111
112
113.. warning::
114  Depending on the ``memory`` parameter the WPS Service will receive
115  different fields (``value`` or ``cache_file``).
116   
117In case you have activated the MapServer support, please refer to
118:ref:`this specific section <kernel-mapserver-main.cfg>`.
119
120
121Identification and Provider
122..........................................
123
124The ``[identification]`` and ``[provider]`` sections are not ZOO-Project
125specific. They provide OGC metadata [#f3]_ and should be set according
126to the `XML Schema Document
127<http://schemas.opengis.net/ows/1.1.0/ows19115subset.xsd>`__ which
128encodes the parts of ISO 19115 used by the common
129*ServiceIdentification* and *ServiceProvider* sections of the
130*GetCapabilities* operation response, known as the service metadata
131XML document.
132
133Details of the common OWS 1.1.0 *ServiceIdentification* section can be
134found in this `XML Schema Document
135<http://schemas.opengis.net/ows/1.1.0/owsServiceIdentification.xsd>`__.
136
137Details of the common OWS 1.1.0 *ServiceProvider* section can be
138found in this `XML Schema Document
139<http://schemas.opengis.net/ows/1.1.0/owsServiceProvider.xsd>`__.
140
141
142Additional sections
143--------------------------------
144
145All the additional sections discribed in the following section are
146optional.
147
148Headers section
149...............................
150
151The ``[headers]`` section can be set in order to define a specific HTTP
152Response header, which will be used for every response. As an example,
153you can check http://zoo-project.org using *curl* command line tool
154and notice the specific header *X-Powered-By: Zoo-Project@Trac*.
155
156In case you want to allow CORS support for POST requests coming from
157``myhost.net``, then you should define the following minimal
158parameters in this section:
159
160.. code-block:: guess
161    :linenos:
162   
163    Access-Control-Allow-Origin=myhost.net
164    Access-Control-Allow-Methods=POST
165    Access-Control-Allow-Headers=content-type
166
167curl section
168...............................
169
170The `[curl]` section is used on windows platform to specify, using the
171`cainfo` parameter, where is located the
172`cacert.pem <https://curl.haxx.se/docs/caextract.html>`__ file on your
173machine. An example bellow is provided to illustrate sur a setting.
174
175.. code-block:: guess
176    :linenos:
177   
178    [curl]
179    cainfo=./cacert.pem
180
181
182
183env section
184...............................
185
186The ``[env]`` section can be used to store specific environment
187variables to be set prior the loading of *Services Provider* and Service execution.
188
189A typical example is when a Service requires the access to a X server
190running on *framebuffer*, which takes to set the DISPLAY environnement
191variable, as follow:
192
193.. code-block:: guess
194    :linenos:
195   
196    [env]
197    DISPLAY=:1
198
199In case you have activated the OTB support, please refer to :ref:`this
200specific section <kernel-orfeotoolbox-main.cfg>`.
201
202lenv section
203...............................
204
205The ``lenv`` section is used by the ZOO-Kernel to store runtime informations
206before the execution of a WPS service, it contains the following
207parameters:
208
209 * ``sid`` (r): The WPS Service unique identifier,
210 * ``status`` (rw): The current progress value ( a value between 0 and
211   100 in percent (**%**) ),
212 * ``cwd`` (r): The current working directory of ZOO-Kernel,
213 * ``message`` (rw): An error message used when ``SERVICE_FAILED`` is returned (optional),
214 * ``cookie`` (rw): The cookie to be returned to the client (for
215   example for authentication purpose).
216 * ``file.pid`` (r): The file used by the ZOO-Kernel to store process identifier.
217 * ``file.sid`` (r): The file used by the ZOO-Kernel to store service identifier.
218 * ``file.responseInit`` (r): The file used by the ZOO-Kernel to store
219   the initial (then final) WPS response.
220 * ``file.responseFinal`` (r): The file used by the ZOO-Kernel to
221   temporary store the final WPS response.
222
223renv section
224...............................
225
226The ``renv`` section is automatically created by the ZOO-Kernel before
227the execution of a WPS service, it contains all the environment
228variables available at runtime (so including the header fields in case
229it is used through http, refer to [https://tools.ietf.org/html/rfc3875
230rfc3875] for more details).
231
232
233senv section
234...............................
235
236The ``senv`` section can be used to store sessions information on the
237server side. Such information can then be accessed automatically from
238the Service if the server is requested using a valid cookie (as
239defined in ``lenv`` section). ZOO-Kernel will store the values set in the
240``senv`` maps on disk, load it and dynamically replace its content to
241the one in the ``main.cfg``. The ``senv`` section must contain the
242following parameter at least:
243
244 * ``XXX``: The session unique identifier where ``XXX`` is the name
245   included in the cookie which is returned.
246
247.. _cookie_example:
248
249For instance, adding the following in the Service source code  :
250
251.. code:: python
252   
253    conf["lenv"]["cookie"]="XXX=XXX1000000; path=/"
254    conf["senv"]={"XXX": "XXX1000000","login": "demoUser"}
255
256means that ZOO-Kernel will create a file named ``sess_XXX1000000.cfg``
257in the ``cacheDir`` directory, and will return the specified cookie to the client. Each time the client will
258request ZOO-Kernel using this cookie, it will automatically load the
259value stored before the Service execution.
260
261Security section
262...............................
263
264The ``[security]`` section can be used to define what headers, the
265ZOO-Kernel has initially received in the request, should be passed
266to other servers for accessing resources (such as WMS, WFS, WCS
267or any other file passed as a reference). This section contains two
268parameters:
269
270 * ``attributes``: The header to pass to other servers (such as
271   Authorization, Cookie, User-Agent ...),
272 * ``hosts``: The host for wich the restriction apply (can be "*" to
273   forward header to every server or a coma separated list of host
274   names, domain, IP).
275
276Both parameters are mandatory.
277
278Suppose you need to share Authorization, Cookie and User-Agent to
279every server for accessing ressources, then yo ucan use the following
280section definition:
281
282.. code::
283
284    [security]
285    attributes=Authorization,Cookie,User-Agent
286    hosts=*
287
288In case only local servers require such header forwarding, you may use
289the following definition:
290
291.. code::
292
293    [security]
294    attributes=Authorization,Cookie,User-Agent
295    hosts=localhost,127.0.0.1
296
297Optionaly, you can also define the shared url(s), meaning that even if
298the ressource requires authentication to be accessed, this
299authentifcation won't be used to define the name for storing the
300file. Hence, two user with different authentication will use the same
301file as it is considerated as shared. You can find bellow a sample
302security section containing the shared parameter. In this example,
303every requests to access the coverage using the url defined in the
304shared parameter (``myHost/cgi-bin/WCS_Server``) will be shared
305between users.
306
307.. code::
308
309    [security]
310    attributes=Authorization,Cookie,User-Agent
311    hosts=localhost,127.0.0.1
312    shared=myHost/cgi-bin/WCS_Server
313
314.. _zoo_activate_db_backend:
315
316Database section
317...............................
318
319The database section allows to configure the
320:ref:`ZOO-Kernel optional database support <zoo_install_db_backend>`.
321
322.. code-block:: guess
323
324        [database]
325        dbname=zoo_project
326        port=5432
327        user=username
328        host=127.0.0.1
329        type=PG
330        schema=public
331
332This will generate strings to be passed to GDAL to connect the
333database server:
334
335.. code-block:: guess
336   
337    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
338
339
340With the previous database section, it will give the following:
341
342.. code-block:: guess
343
344    PG:"dbname=zoo_project host=127.0.0.1 port=5432 user=username"
345
346Please refer to this `section <zoo_create_db_backend>`_ to learn how
347to setup the database.
348
349.. _zoo_activate_metadb:
350
351Metadb section
352...............................
353
354The metadb section allows to configure the ZOO-Kernel to access :ref:`the
355metadata information about WPS Services <zoo_create_metadb>` by using
356a PostgreSQL database in addition to the zcfg files.
357
358.. code-block:: guess
359
360        [metadb]
361        dbname=zoo_metadb
362        port=5432
363        user=username
364        host=127.0.0.1
365        type=PG
366
367This will generate strings to be passed to GDAL to connect the
368database server:
369
370.. code-block:: guess
371   
372    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
373
374
375With the previous database section, it will give the following:
376
377.. code-block:: guess
378
379    PG:"dbname=zoo_metadb host=127.0.0.1 port=5432 user=username"
380
381Please refer to this `section <zoo_create_metadb>`_ to learn how
382to setup the database.
383
384Include section
385...............................
386
387The ``[include]`` section (optional) lists explicitely a set of service configuration files
388the the ZOO-Kernel should parse, e.g.,
389
390
391.. code-block:: guess
392    :linenos:
393   
394    [include]
395    servicename1 = /my/service/repository/service1.zcfg
396    servicename2 = /my/service/repository/service2.zcfg
397
398The ``[include]`` section may be used to control which services are exposed to particular user groups.
399While service configuration files (.zcfg) may be located in a common repository or in arbitrary folders,
400main.cfg files at different URLs may include different subsets of services.
401
402When the ZOO-Kernel handles a request, it will first check if there is an ``[include]``
403section in main.cfg and then search for other .zcfg files in the current working directory (CWD) and
404subdirectories. If an included service happens to be located in a CWD (sub)directory,
405it will be published by its name in the ``[include]`` section. For example, the service
406``/[CWD]/name/space/myService.zcfg``
407would normally be published as name.space.myService, but if it is listed in the ``[include]`` section
408it will be published simply as myService:
409
410.. code-block:: guess
411    :linenos:
412   
413    [include]
414    myService =  /[CWD]/name/space/myService.zcfg
415
416On the other hand, with
417
418.. code-block:: guess
419    :linenos:
420   
421    [include]
422    myService =  /some/other/dir/myService.zcfg
423
424there would be two distinct services published as myService and name.space.myService, respectively,
425with two different zcfg files.
426
427.. note::
428  As currently implemented, the ZOO-Kernel searches the CWD for the library files of
429  included services if the ``libPath`` parameter is not set.
430
431
432OpenAPI Specification configuration file
433-----------------------------------------
434
435Since revision 949 of the ZOO-Kernel, you can now activate the OGC
436API - Processing support. In such a case you will need to have an
437``oas.cfg`` file located in tne same directory where the ``main.cfg`` is.
438
439This ``oas.cfg`` file gets the same syntactic rules than the
440``main.cfg``. The ZOO-Kernel uses this file to produce information
441about the open API specification it is referring to.
442
443The first section to be found in the ``oas.cfg`` file should be the
444``[openapi]``. It contains the following parameters:
445
446 * ``rootUrl``: the URL to access the ZOO-Kernel using OGC API - Processing
447 * ``links``: the links provided from the root
448 * ``paths``: the full paths list
449 * ``parameters``: the parameters list defined in paths
450 * ``header_parameters``: the parameters list client applications can send as header
451 * ``version``: the Open API Specification version
452   
453For any links and paths ``/A`` defined, you will have a corresponding
454``[/A]`` and ``[A]`` sections. In the ``[/A]`` section you will define
455the rel, type and title used from the root URL to produce the `links
456<https://github.com/opengeospatial/wps-rest-binding/blob/master/core/openapi/schemas/link.yaml>`__
457list and the `paths object
458<https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject>`__
459from. In the corresponding ``[A]`` section, you will define the
460following parameters:
461
462 * ``method``: the HTTP method to use to access this resource
463 * ``title``: resource title
464 * ``abstract``: resource description
465 * ``tags``: tags to classify this resource
466 * ``tags_description``: the tag description
467 * ``schema``: the schema specifying the resource
468
469In case you want to define multiple methods to access a resource,  you
470can then use the length parameter to define the number of parameters
471group to parse, then use ``method_1``, ``title_1``, ``abstract_1``,
472``tags_1``, ``tags_description_1`` and ``schema_1`` and so on to add
473one or more access method (and other attributes) to this resource.
474
475When declaring resource access you may want to add a parameter to your
476request. In such a case, you can add a parameter named "parameters"
477which contain the supported parameters list. All parameters defined
478should be rooted in the components field. Parameters which can be used
479in the path will be identified by ``{NAME}`` and will get a specific
480section for its definition:
481
482 * ``type``: nature of the parameter (i.e. string)
483 * ``title``: parameter title
484 * ``abstract``: parameter description
485 * ``in``: where the parameter can be used (ie. path, header, query)
486 * ``required``: define if the parameter is optional (false) or not (true)
487 * ``example``: (optional) provide an example value / URL
488   
489In addition to the sections defined previously, there are three other
490sections that we did not cover yet. Theses sections are:
491
492 * ``[requestBody]``: defining the request body abstract (description), type (application/json) and schema (reference).
493 * ``[exception]``: defining the exception bastract (description), type (application/json) and schema (reference).
494 * ``[conformTo]``: referring to links list of the requirements classes the server implements and conforms to
495
496For more information on how to interact with this WPS REST Binding, please refer
497to this `page
498<https://github.com/opengeospatial/wps-rest-binding#overview>`__ or use
499the `Swagger UI <https://swagger.io/tools/swagger-ui/>`__. A live
500instance is available `here <https://demo.mapmint.com/swagger-ui/dist/>`__.
501 
502.. rubric:: Footnotes
503
504.. [#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.
505.. [#f2] Usefull when the :ref:`kernel-mapserver` is activated (available since ZOO-Project version 1.3.0).
506.. [#f3] ZOO-Kernel and MapServer are sharing the same metadata for OGC Web Services if the :ref:`kernel-mapserver` is activated.
507
508   
Note: See TracBrowser for help on using the repository browser.

Search

Context Navigation

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