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

Last change on this file since 920 was 920, checked in by djay, 5 years ago

Fix documentation typos.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 14.1 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 * ``memory``: (Optional) can take the value ``load`` to ensure that
97   the value field of the inputs data will be filled by the ZOO-Kernel
98   or ``protected`` to have only the ``cache_file`` filled.
99
100
101.. warning::
102  The ``libPath`` parameter is currently only recognized by services implemented
103  in C/C++ or PHP, and may be moved to another section in future versions.
104
105
106.. warning::
107  Depending on the ``memory`` parameter the WPS Service will receive
108  different fields (``value`` or ``cache_file``).
109   
110In case you have activated the MapServer support, please refer to
111:ref:`this specific section <kernel-mapserver-main.cfg>`.
112
113
114Identification and Provider
115..........................................
116
117The ``[identification]`` and ``[provider]`` sections are not ZOO-Project
118specific. They provide OGC metadata [#f3]_ and should be set according
119to the `XML Schema Document
120<http://schemas.opengis.net/ows/1.1.0/ows19115subset.xsd>`__ which
121encodes the parts of ISO 19115 used by the common
122*ServiceIdentification* and *ServiceProvider* sections of the
123*GetCapabilities* operation response, known as the service metadata
124XML document.
125
126Details of the common OWS 1.1.0 *ServiceIdentification* section can be
127found in this `XML Schema Document
128<http://schemas.opengis.net/ows/1.1.0/owsServiceIdentification.xsd>`__.
129
130Details of the common OWS 1.1.0 *ServiceProvider* section can be
131found in this `XML Schema Document
132<http://schemas.opengis.net/ows/1.1.0/owsServiceProvider.xsd>`__.
133
134
135Additional sections
136--------------------------------
137
138All the additional sections discribed in the following section are
139optional.
140
141Headers section
142...............................
143
144The ``[headers]`` section can be set in order to define a specific HTTP
145Response header, which will be used for every response. As an example,
146you can check http://zoo-project.org using *curl* command line tool
147and notice the specific header *X-Powered-By: Zoo-Project@Trac*.
148
149In case you want to allow CORS support for POST requests coming from
150``myhost.net``, then you should define the following minimal
151parameters in this section:
152
153.. code-block:: guess
154    :linenos:
155   
156    Access-Control-Allow-Origin=myhost.net
157    Access-Control-Allow-Methods=POST
158    Access-Control-Allow-Headers=content-type
159
160
161env section
162...............................
163
164The ``[env]`` section can be used to store specific environment
165variables to be set prior the loading of *Services Provider* and Service execution.
166
167A typical example is when a Service requires the access to a X server
168running on *framebuffer*, which takes to set the DISPLAY environnement
169variable, as follow:
170
171.. code-block:: guess
172    :linenos:
173   
174    [env]
175    DISPLAY=:1
176
177In case you have activated the OTB support, please refer to :ref:`this
178specific section <kernel-orfeotoolbox-main.cfg>`.
179
180lenv section
181...............................
182
183The ``lenv`` section is used by the ZOO-Kernel to store runtime informations
184before the execution of a WPS service, it contains the following
185parameters:
186
187 * ``sid`` (r): The WPS Service unique identifier,
188 * ``status`` (rw): The current progress value ( a value between 0 and
189   100 in percent (**%**) ),
190 * ``cwd`` (r): The current working directory of ZOO-Kernel,
191 * ``message`` (rw): An error message used when ``SERVICE_FAILED`` is returned (optional),
192 * ``cookie`` (rw): The cookie to be returned to the client (for
193   example for authentication purpose).
194 * ``file.pid`` (r): The file used by the ZOO-Kernel to store process identifier.
195 * ``file.sid`` (r): The file used by the ZOO-Kernel to store service identifier.
196 * ``file.responseInit`` (r): The file used by the ZOO-Kernel to store
197   the initial (then final) WPS response.
198 * ``file.responseFinal`` (r): The file used by the ZOO-Kernel to
199   temporary store the final WPS response.
200
201renv section
202...............................
203
204The ``renv`` section is automatically created by the ZOO-Kernel before
205the execution of a WPS service, it contains all the environment
206variables available at runtime (so including the header fields in case
207it is used through http, refer to [https://tools.ietf.org/html/rfc3875
208rfc3875] for more details).
209
210
211senv section
212...............................
213
214The ``senv`` section can be used to store sessions information on the
215server side. Such information can then be accessed automatically from
216the Service if the server is requested using a valid cookie (as
217defined in ``lenv`` section). ZOO-Kernel will store the values set in the
218``senv`` maps on disk, load it and dynamically replace its content to
219the one in the ``main.cfg``. The ``senv`` section must contain the
220following parameter at least:
221
222 * ``XXX``: The session unique identifier where ``XXX`` is the name
223   included in the cookie which is returned.
224
225.. _cookie_example:
226
227For instance, adding the following in the Service source code  :
228
229.. code:: python
230   
231    conf["lenv"]["cookie"]="XXX=XXX1000000; path=/"
232    conf["senv"]={"XXX": "XXX1000000","login": "demoUser"}
233
234means that ZOO-Kernel will create a file named ``sess_XXX1000000.cfg``
235in the ``cacheDir`` directory, and will return the specified cookie to the client. Each time the client will
236request ZOO-Kernel using this cookie, it will automatically load the
237value stored before the Service execution.
238
239Security section
240...............................
241
242The ``[security]`` section can be used to define what headers, the
243ZOO-Kernel has initially received in the request, should be passed
244to other servers for accessing resources (such as WMS, WFS, WCS
245or any other file passed as a reference). This section contains two
246parameters:
247
248 * ``attributes``: The header to pass to other servers (such as
249   Authorization, Cookie, User-Agent ...),
250 * ``hosts``: The host for wich the restriction apply (can be "*" to
251   forward header to every server or a coma separated list of host
252   names, domain, IP).
253
254Both parameters are mandatory.
255
256Suppose you need to share Authorization, Cookie and User-Agent to
257every server for accessing ressources, then yo ucan use the following
258section definition:
259
260.. code::
261
262    [security]
263    attributes=Authorization,Cookie,User-Agent
264    hosts=*
265
266In case only local servers require such header forwarding, you may use
267the following definition:
268
269.. code::
270
271    [security]
272    attributes=Authorization,Cookie,User-Agent
273    hosts=localhost,127.0.0.1
274
275Optionaly, you can also define the shared url(s), meaning that even if
276the ressource requires authentication to be accessed, this
277authentifcation won't be used to define the name for storing the
278file. Hence, two user with different authentication will use the same
279file as it is considerated as shared. You can find bellow a sample
280security section containing the shared parameter. In this example,
281every requests to access the coverage using the url defined in the
282shared parameter (``myHost/cgi-bin/WCS_Server``) will be shared
283between users.
284
285.. code::
286
287    [security]
288    attributes=Authorization,Cookie,User-Agent
289    hosts=localhost,127.0.0.1
290    shared=myHost/cgi-bin/WCS_Server
291
292.. _zoo_activate_db_backend:
293
294Database section
295...............................
296
297The database section allows to configure the
298:ref:`ZOO-Kernel optional database support <zoo_install_db_backend>`.
299
300.. code-block:: guess
301
302        [database]
303        dbname=zoo_project
304        port=5432
305        user=username
306        host=127.0.0.1
307        type=PG
308        schema=public
309
310This will generate strings to be passed to GDAL to connect the
311database server:
312
313.. code-block:: guess
314   
315    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
316
317
318With the previous database section, it will give the following:
319
320.. code-block:: guess
321
322    PG:"dbname=zoo_project host=127.0.0.1 port=5432 user=username"
323
324Please refer to this `section <zoo_create_db_backend>`_ to learn how
325to setup the database.
326
327.. _zoo_activate_metadb:
328
329Metadb section
330...............................
331
332The metadb section allows to configure the ZOO-Kernel to access :ref:`the
333metadata information about WPS Services <zoo_create_metadb>` by using
334a PostgreSQL database in addition to the zcfg files.
335
336.. code-block:: guess
337
338        [metadb]
339        dbname=zoo_metadb
340        port=5432
341        user=username
342        host=127.0.0.1
343        type=PG
344
345This will generate strings to be passed to GDAL to connect the
346database server:
347
348.. code-block:: guess
349   
350    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
351
352
353With the previous database section, it will give the following:
354
355.. code-block:: guess
356
357    PG:"dbname=zoo_metadb host=127.0.0.1 port=5432 user=username"
358
359Please refer to this `section <zoo_create_metadb>`_ to learn how
360to setup the database.
361
362Include section
363...............................
364
365The ``[include]`` section (optional) lists explicitely a set of service configuration files
366the the ZOO-Kernel should parse, e.g.,
367
368
369.. code-block:: guess
370    :linenos:
371   
372    [include]
373    servicename1 = /my/service/repository/service1.zcfg
374    servicename2 = /my/service/repository/service2.zcfg
375
376The ``[include]`` section may be used to control which services are exposed to particular user groups.
377While service configuration files (.zcfg) may be located in a common repository or in arbitrary folders,
378main.cfg files at different URLs may include different subsets of services.
379
380When the ZOO-Kernel handles a request, it will first check if there is an ``[include]``
381section in main.cfg and then search for other .zcfg files in the current working directory (CWD) and
382subdirectories. If an included service happens to be located in a CWD (sub)directory,
383it will be published by its name in the ``[include]`` section. For example, the service
384``/[CWD]/name/space/myService.zcfg``
385would normally be published as name.space.myService, but if it is listed in the ``[include]`` section
386it will be published simply as myService:
387
388.. code-block:: guess
389    :linenos:
390   
391    [include]
392    myService =  /[CWD]/name/space/myService.zcfg
393
394On the other hand, with
395
396.. code-block:: guess
397    :linenos:
398   
399    [include]
400    myService =  /some/other/dir/myService.zcfg
401
402there would be two distinct services published as myService and name.space.myService, respectively,
403with two different zcfg files.
404
405.. note::
406  As currently implemented, the ZOO-Kernel searches the CWD for the library files of
407  included services if the ``libPath`` parameter is not set.
408
409     
410.. rubric:: Footnotes
411
412.. [#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.
413.. [#f2] Usefull when the :ref:`kernel-mapserver` is activated (available since ZOO-Project version 1.3.0).
414.. [#f3] ZOO-Kernel and MapServer are sharing the same metadata for OGC Web Services if the :ref:`kernel-mapserver` is activated.
415
416   
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