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

Last change on this file since 908 was 817, checked in by djay, 8 years ago

Forward headers defined in the security section in the main.cfg #139.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 12.4 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
129All the additional sections discribed in the following section are
130optional.
131
132Headers section
133...............................
134
135The ``[headers]`` section can be set in order to define a specific HTTP
136Response header, which will be used for every response. As an example,
137you can check http://zoo-project.org using *curl* command line tool
138and notice the specific header *X-Powered-By: Zoo-Project@Trac*.
139
140In case you want to allow CORS support for POST requests coming from
141``myhost.net``, then you should define the following minimal
142parameters in this section:
143
144.. code-block:: guess
145    :linenos:
146   
147    Access-Control-Allow-Origin=myhost.net
148    Access-Control-Allow-Methods=POST
149    Access-Control-Allow-Headers=content-type
150
151
152env section
153...............................
154
155The ``[env]`` section can be used to store specific environment
156variables to be set prior the loading of *Services Provider* and Service execution.
157
158A typical example is when a Service requires the access to a X server
159running on *framebuffer*, which takes to set the DISPLAY environnement
160variable, as follow:
161
162.. code-block:: guess
163    :linenos:
164   
165    [env]
166    DISPLAY=:1
167
168In case you have activated the OTB support, please refer to :ref:`this
169specific section <kernel-orfeotoolbox-main.cfg>`.
170
171lenv section
172...............................
173
174The ``lenv`` section is used by the ZOO-Kernel to store runtime informations
175before the execution of a WPS service, it contains the following
176parameters:
177
178 * ``sid`` (r): The WPS Service unique identifier,
179 * ``status`` (rw): The current progress value ( a value between 0 and
180   100 in percent (**%**) ),
181 * ``cwd`` (r): The current working directory of ZOO-Kernel,
182 * ``message`` (rw): An error message used when ``SERVICE_FAILED`` is returned (optional),
183 * ``cookie`` (rw): The cookie to be returned to the client (for
184   example for authentication purpose).
185 * ``file.pid`` (r): The file used by the ZOO-Kernel to store process identifier.
186 * ``file.sid`` (r): The file used by the ZOO-Kernel to store service identifier.
187 * ``file.responseInit`` (r): The file used by the ZOO-Kernel to store
188   the initial (then final) WPS response.
189 * ``file.responseFinal`` (r): The file used by the ZOO-Kernel to
190   temporary store the final WPS response.
191
192renv section
193...............................
194
195The ``renv`` section is automatically created by the ZOO-Kernel before
196the execution of a WPS service, it contains all the environment
197variables available at runtime (so including the header fields in case
198it is used through http, refer to [https://tools.ietf.org/html/rfc3875
199rfc3875] for more details).
200
201
202senv section
203...............................
204
205The ``senv`` section can be used to store sessions information on the
206server side. Such information can then be accessed automatically from
207the Service if the server is requested using a valid cookie (as
208defined in ``lenv`` section). ZOO-Kernel will store the values set in the
209``senv`` maps on disk, load it and dynamically replace its content to
210the one in the ``main.cfg``. The ``senv`` section must contain the
211following parameter at least:
212
213 * ``XXX``: The session unique identifier where ``XXX`` is the name
214   included in the cookie which is returned.
215
216.. _cookie_example:
217
218For instance, adding the following in the Service source code  :
219
220.. code:: python
221   
222    conf["lenv"]["cookie"]="XXX=XXX1000000; path=/"
223    conf["senv"]={"XXX": "XXX1000000","login": "demoUser"}
224
225means that ZOO-Kernel will create a file named ``sess_XXX1000000.cfg``
226in the ``cacheDir`` directory, and will return the specified cookie to the client. Each time the client will
227request ZOO-Kernel using this cookie, it will automatically load the
228value stored before the Service execution.
229
230Security section
231...............................
232
233The ``[security]`` section can be used to define what headers, the
234ZOO-Kernel has initially received in the request, should be passed
235to other servers for accessing resources (such as WMS, WFS, WCS
236or any other file passed as a reference). This section contains two
237parameters:
238
239 * ``attributes``: The header to pass to other servers (such as
240   Authorization, Cookie, User-Agent ...),
241 * ``hosts``: The host for wich the restriction apply (can be "*" to
242   forward header to every server or a coma separated list of host
243   names, domain, IP).
244
245Both parameters are mandatory.
246
247Suppose you need to share Authorization, Cookie and User-Agent to
248every server for accessing ressources, then yo ucan use the following
249section definition:
250
251.. code::
252
253    [security]
254    attributes=Authorization,Cookie,User-Agent
255    hosts=*
256
257In case only local servers require such header forwarding, you may use
258the following definition:
259
260.. code::
261
262    [security]
263    attributes=Authorization,Cookie,User-Agent
264    hosts=localhost,127.0.0.1
265
266
267.. _zoo_activate_db_backend:
268
269Database section
270...............................
271
272The database section allows to configure the
273:ref:`ZOO-Kernel optional database support <zoo_install_db_backend>`.
274
275.. code-block:: guess
276
277        [database]
278        dbname=zoo_project
279        port=5432
280        user=username
281        host=127.0.0.1
282        type=PG
283        schema=public
284
285This will generate strings to be passed to GDAL to connect the
286database server:
287
288.. code-block:: guess
289   
290    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
291
292
293With the previous database section, it will give the following:
294
295.. code-block:: guess
296
297    PG:"dbname=zoo_project host=127.0.0.1 port=5432 user=username"
298
299Please refer to this `section <zoo_create_db_backend>`_ to learn how
300to setup the database.
301
302Include section
303...............................
304
305The ``[include]`` section (optional) lists explicitely a set of service configuration files
306the the ZOO-Kernel should parse, e.g.,
307
308
309.. code-block:: guess
310    :linenos:
311   
312    [include]
313    servicename1 = /my/service/repository/service1.zcfg
314    servicename2 = /my/service/repository/service2.zcfg
315
316The ``[include]`` section may be used to control which services are exposed to particular user groups.
317While service configuration files (.zcfg) may be located in a common repository or in arbitrary folders,
318main.cfg files at different URLs may include different subsets of services.
319
320When the ZOO-Kernel handles a request, it will first check if there is an ``[include]``
321section in main.cfg and then search for other .zcfg files in the current working directory (CWD) and
322subdirectories. If an included service happens to be located in a CWD (sub)directory,
323it will be published by its name in the ``[include]`` section. For example, the service
324``/[CWD]/name/space/myService.zcfg``
325would normally be published as name.space.myService, but if it is listed in the ``[include]`` section
326it will be published simply as myService:
327
328.. code-block:: guess
329    :linenos:
330   
331    [include]
332    myService =  /[CWD]/name/space/myService.zcfg
333
334On the other hand, with
335
336.. code-block:: guess
337    :linenos:
338   
339    [include]
340    myService =  /some/other/dir/myService.zcfg
341
342there would be two distinct services published as myService and name.space.myService, respectively,
343with two different zcfg files.
344
345.. note::
346  As currently implemented, the ZOO-Kernel searches the CWD for the library files of
347  included services if the ``libPath`` parameter is not set.
348
349     
350.. rubric:: Footnotes
351
352.. [#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.
353.. [#f2] Usefull when the :ref:`kernel-mapserver` is activated (available since ZOO-Project version 1.3.0).
354.. [#f3] ZOO-Kernel and MapServer are sharing the same metadata for OGC Web Services if the :ref:`kernel-mapserver` is activated.
355
356   
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