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

Last change on this file since 786 was 784, checked in by djay, 8 years ago

Give the capability to store the main.cfg file in sysconfdir and the services in servicePath if defined in the [main] section.

  • Property svn:keywords set to Date Author
  • Property svn:mime-type set to text/plain
File size: 9.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   paramater 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
94In case you have activated the MapServer support, please refer to
95:ref:`this specific section <kernel-mapserver-main.cfg>`.
96
97
98Identification and Provider
99..........................................
100
101The ``[identification]`` and ``[provider]`` sections are not ZOO-Project
102specific. They provide OGC metadata [#f3]_ and should be set according
103to the `XML Schema Document
104<http://schemas.opengis.net/ows/1.1.0/ows19115subset.xsd>`__ which
105encodes the parts of ISO 19115 used by the common
106*ServiceIdentification* and *ServiceProvider* sections of the
107*GetCapabilities* operation response, known as the service metadata
108XML document.
109
110Details of the common OWS 1.1.0 *ServiceIdentification* section can be
111found in this `XML Schema Document
112<http://schemas.opengis.net/ows/1.1.0/owsServiceIdentification.xsd>`__.
113
114Details of the common OWS 1.1.0 *ServiceProvider* section can be
115found in this `XML Schema Document
116<http://schemas.opengis.net/ows/1.1.0/owsServiceProvider.xsd>`__.
117
118
119Additional sections
120--------------------------------
121
122Headers section
123...............................
124
125The ``[headers]`` section can be set in order to define a specific HTTP
126Response header, which will be used for every response. As an example,
127you can check http://zoo-project.org using *curl* command line tool
128and notice the specific header *X-Powered-By: Zoo-Project@Trac*.
129
130In case you want to allow CORS support for POST requests coming from
131``myhost.net``, then you should define the following minimal
132parameters in this section:
133
134.. code-block:: guess
135    :linenos:
136   
137    Access-Control-Allow-Origin=myhost.net
138    Access-Control-Allow-Methods=POST
139    Access-Control-Allow-Headers=content-type
140
141
142env section
143...............................
144
145The ``[env]`` section can be used to store specific environment
146variables to be set prior the loading of *Services Provider* and Service execution.
147
148A typical example is when a Service requires the access to a X server
149running on *framebuffer*, which takes to set the DISPLAY environnement
150variable, as follow:
151
152.. code-block:: guess
153    :linenos:
154   
155    [env]
156    DISPLAY=:1
157
158In case you have activated the OTB support, please refer to :ref:`this
159specific section <kernel-orfeotoolbox-main.cfg>`.
160
161lenv section
162...............................
163
164The ``lenv`` section is used by the ZOO-Kernel to store runtime informations
165before the execution of a WPS service, it contains the following
166parameters:
167
168 * ``sid`` (r): The WPS Service unique identifier,
169 * ``status`` (rw): The current progress value ( a value between 0 and
170   100 in percent (**%**) ),
171 * ``cwd`` (r): The current working directory of ZOO-Kernel,
172 * ``message`` (rw): An error message used when ``SERVICE_FAILED`` is returned (optional),
173 * ``cookie`` (rw): The cookie to be returned to the client (for
174   example for authentication purpose).
175 * ``file.pid`` (r): The file used by the ZOO-Kernel to store process identifier.
176 * ``file.sid`` (r): The file used by the ZOO-Kernel to store service identifier.
177 * ``file.responseInit`` (r): The file used by the ZOO-Kernel to store
178   the initial (then final) WPS response.
179 * ``file.responseFinal`` (r): The file used by the ZOO-Kernel to
180   temporary store the final WPS response.
181
182renv section
183...............................
184
185The ``renv`` section is automatically created by the ZOO-Kernel before
186the execution of a WPS service, it contains all the environment
187variables available at runtime (so including the header fields in case
188it is used through http, refer to [https://tools.ietf.org/html/rfc3875
189rfc3875] for more details).
190
191
192senv section
193...............................
194
195The ``senv`` section can be used to store sessions information on the
196server side. Such information can then be accessed automatically from
197the Service if the server is requested using a valid cookie (as
198defined in ``lenv`` section). ZOO-Kernel will store the values set in the
199``senv`` maps on disk, load it and dynamically replace its content to
200the one in the ``main.cfg``. The ``senv`` section must contain the
201following parameter at least:
202
203 * ``XXX``: The session unique identifier where ``XXX`` is the name
204   included in the cookie which is returned.
205
206.. _cookie_example:
207
208For instance, adding the following in the Service source code  :
209
210.. code:: python
211   
212    conf["lenv"]["cookie"]="XXX=XXX1000000; path=/"
213    conf["senv"]={"XXX": "XXX1000000","login": "demoUser"}
214
215means that ZOO-Kernel will create a file named ``sess_XXX1000000.cfg``
216in the ``cacheDir`` directory, and will return the specified cookie to the client. Each time the client will
217request ZOO-Kernel using this cookie, it will automatically load the
218value stored before the Service execution.
219
220.. _zoo_activate_db_backend:
221
222Database section
223...............................
224
225The database section allows to configure the
226:ref:`ZOO-Kernel optional database support <zoo_install_db_backend>`.
227
228.. code-block:: guess
229
230        [database]
231        dbname=zoo_project
232        port=5432
233        user=username
234        host=127.0.0.1
235        type=PG
236        schema=public
237
238This will generate strings to be passed to GDAL to connect the
239database server:
240
241.. code-block:: guess
242   
243    <type>:host=<host> port=<port>  user=<user> dbname=<dbname>
244
245
246With the previous database section, it will give the following:
247
248.. code-block:: guess
249
250    PG:"dbname=zoo_project host=127.0.0.1 port=5432 user=username"
251
252Please refer to this `section <zoo_create_db_backend>`_ to learn how
253to setup the database.
254
255     
256.. rubric:: Footnotes
257
258.. [#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.
259.. [#f2] Usefull when the :ref:`kernel-mapserver` is activated (available since ZOO-Project version 1.3.0).
260.. [#f3] ZOO-Kernel and MapServer are sharing the same metadata for OGC Web Services if the :ref:`kernel-mapserver` is activated.
261
262   
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