.. _tinyows_configfile:
*****************************************************************************
Configuring TinyOWS with an XML File
*****************************************************************************
The simplest way to configure TinyOWS is with a single XML file called ``config.xml``.
The default path is ``/usr/local/tinyows/config.xml``. You can
also use ``TINYOWS_CONFIG_FILE`` environment variable to set your own path.
Configuration file simple Example
---------------------------------
An example ``config.xml`` file is in the demo directory:
.. code-block:: xml
Testing your config.xml file
----------------------------
Once you have a config.xml file related to your service,
launch TinyOWS with the --check option to validate your configuration
file, test your database connection, and list the layers to be used:
.. code-block:: bash
./tinyows --check
Config File: OK
PG Connection: OK
Available layers:
- public.world -> 4326 RW
- public.france -> 27582 RW
Structure of the config.xml file
--------------------------------
TinyOWS Element
===============
TinyOWS is the root element.
He is mandatory, and must contains some system informations about the service itself.
Some globals service options could also be switched on or off at this level.
==================== ========= ======= ===========
Attribute Required? Default Description
==================== ========= ======= ===========
online_resource mandatory URL where the service is located, e.g: ``http://127.0.0.1/cgi-bin/tinyows``
schema_dir mandatory Path where TinyOWS schema dir is located e.g: ``/usr/local/tinyows/schema/``
log optional Path where TinyOWS logs input requests. e.g: ``/var/log/tinyows.log``. This file must be writable by the user that owns the TinyOWS process.
log_level optional 0 Bit field value to indicate what to log: 1: ERROR, 2: EVENT, 4: HTTP QUERY, 8: SQL
degree_precision optional 6 Indicate how many digits of decimal precision when positions are in latitude/longitude.
meter_precision optional 0 Indicate how many digits of decimal precision to use when positions are in meters.
display_bbox optional 1 Flag to indicate if bounding box should be computed for WFS GML ``GetFeature`` output. It's mandatory in WFS specification. But as it's time consuming it could be interesting to be able to deactivate it.
estimated_extent optional 0 Flag to indicate if TinyOWS should use estimated_extent (faster but less accurate).
check_schema optional 1 Flag to indicate if input data must be checked against schema before to be executed. Caution, schema validation is an important part of security. Disable this attribute at your peril.
check_valid_geom optional 1 Flag to indicate if geometry OGC SFS 1.1 validation should be done prior to execute a transaction.
encoding optional UTF-8 Output encoding. Other values could be ISO-8859-1 for instance. No encoding conversion is done on data; this attribute is declarative.
expose_pk optional 0 Flag to indicate if TinyOWS should expose PK in schema (and so require them in Transaction query).
==================== ========= ======= ===========
Limits Element
==============
Limits Element provides a maximum for the server output.
It could help to prevent a denial of service attack, or an abnormally
large user query, from crashing your server.
This element is optional.
Limits attributes
==================== ========= ======= ===========
Attribute Required? Default Description
==================== ========= ======= ===========
features optional Use to set maximum number of features returned to WFS client, on ``GetFeature`` request
geobbox optional WGS-84 Geographic bounding bbox, used to indicate maximum extent: East,West,North,South
==================== ========= ======= ===========
.. code-block:: xml
...
...
PostgreSQL Connection
=====================
PostgreSQL connection element.
This element is mandatory.
==================== ========= ========= ===========
Attribute Required? Default Description
==================== ========= ========= ===========
host optional localhost Name (or IP) to PostgreSQL server (default is localhost)
user optional PostgreSQL user to connect (default is the system user used to run the server)
password optional PostgreSQL password connection
dbname optional PostGIS database (by default, same as the system user used to run the server
port optional 5432 PostgreSQL port number
encoding optional UTF-8 PostgreSQL DB encoding, as specified in http://www.postgresql.org/docs/9.0/static/multibyte.html#CHARSET-TABLE
==================== ========= ========= ===========
.. code-block:: xml
...
...
Metadata and Contact Elements
=============================
Used to provide information about the service itself.
These two elements are mandatory.
Metadata attributes
+++++++++++++++++++
==================== ========= ======= ===========
Attribute Required? Default Description
==================== ========= ======= ===========
name mandatory Web Service Name
title mandatory Web Service Title
keywords optional Web Service Keywords list (comma separated list)
fees optional Web Service Fees
access_constraints optional Web Service Access Constraints
==================== ========= ======= ===========
Abstract Element
++++++++++++++++
The Abstract element is an optional child element of Metadata. It
is a place for a free-formatted text description of the service.
Contact attributes
++++++++++++++++++
==================== ========= ======= ===========
Attribute Required? Default Description
==================== ========= ======= ===========
name mandatory Web Service Contact Name
site mandatory Web Service Contact URL
email mandatory Web Service Contact Email
individual_name optional Web Service Contact Individual Name
position optional Web Service Contact Position
phone optional Web Service Contact Phone
fax optional Web Service Contact Fax
online_resource optional Web Service Contact URL (e.g additional Metadatas)
address optional Web Service Contact Postal Address
postcode optional Web Service Contact Postcode
city optional Web Service Contact City
administrative_area optional Web Service Contact Administrative Area
country optional Web Service Contact Country
hours_of_service optional Web Service Contact Hours of Services
contact_instructions optional Web Service Contact Instructions ||
==================== ========= ======= ===========
Contact and Metadata example with only mandatory attributes:
.. code-block:: xml
Layer Element
=============
Layer element is used to set all layers provided by the service.
Although this element is technically optional, omitting it will cause no layer at all to be provided.
==================== ========= ======== ========= ============
Attribute Required? Default Inherits? Description
==================== ========= ======== ========= ============
ns_prefix mandatory Yes Layer's Namespace Prefix used in WFS
ns_uri mandatory Yes Layer's Namespace URI used in WFS
name mandatory No Layer's Name
title mandatory No Layer's Title
retrievable optional false Yes If true, layer is retrievable on WFS ``GetFeature`` request
writable optional false Yes If true, layer is editable with WFS Transaction request
schema optional 'public' No PostgreSQL Schema name.
abstract optional No Abstract text
keywords optional No Keywords (comma separated list)
srid optional Yes Comma separated list of output SRID
geobbox optional Yes WGS-84 bbox of max extent: East,West,North,South
==================== ========= ======== ========= ============
.. code-block:: xml
...
...
Nested Layers
+++++++++++++
Layer entities could be nested, properties in this case are inherited.
.. code-block:: xml
...
...