Configuring TinyOWS with an XML File

The simplest way to configure TinyOWS is with a single XML file called tinyows.xml.

The default path is /etc/tinyows.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:

<tinyows online_resource="http://127.0.0.1/cgi-bin/tinyows"
         schema_dir="/usr/local/tinyows/schema/">

 <pg host="127.0.0.1" user="postgres" password="postgres" dbname="tinyows_demo" port="5432"/>

 <metadata name="TinyOWS Server"
           title="TinyOWS Server - Demo Service" />

 <layer retrievable="1"
        writable="1"
        ns_prefix="tows"
        ns_uri="http://www.mapserver.org/tinyows/"
        name="world"
        title="World Administrative Boundaries" />

 <layer retrievable="1"
        writable="1"
        ns_prefix="tows"
        ns_uri="http://www.mapserver.org/tinyows/"
        name="france"
        title="French Administrative Sub Boundaries (IGN - GeoFLA Departements)" />

</tinyows>

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:

./tinyows --check
 TinyOWS version:   1.1.0
 FCGI support:      Yes
 Config File Path:  /etc/tinyows.xml (TinyOWS XML)
 PostGIS Version:   2.1.0
 PostGIS dsn:       host=127.0.0.1 user=postgres password=postgres dbname=foo port=5432
 Output Encoding:   UTF-8
 Database Encoding: UTF8
 Schema dir:        /usr/local/share/tinyows/schema/
 Display bbox:      Yes
 Estimated extent:  No
 Check schema:      Yes
 Check valid geoms: No
 Available layers:
  - public.commune (2154) -> tows.commune [RW]
  - public.world (4326) -> tows.world [RW]

Structure of the config.xml file

TinyOWS Element

TinyOWS is the root element. He is mandatory, and must contains some system information 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. e.g: 15 to log all.
degree_precision optional 6 Indicate how many digits of decimal precision when coordinates are express in latitude/longitude.
meter_precision optional 0 Indicate how many digits of decimal precision to use when coordinates are projected (so meter unit).
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 slightly 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 OGC SFS 1.1 geometry 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).
wfs_default_version optional   String version to indicate WFS default version, 1.0.0 or 1.1.0 for instance.

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   Geographic bounding bbox, used to indicate maximum extent: East,West,North,South
<tinyows>
 ...
 <limits features="10000" />
 ...
</tinyows>

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
<tinyows>
 ...
 <pg host="127.0.0.1"
        user="postgres"
        password="postgres"
        dbname="gis_data"
        port="5432" />
  ...
</tinyows>

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:

<metadata name="TinyOWS Server"
          title="TinyOWS Server - Demo Service" />

<contact name="TinyOWS Server"
         site="http://www.mapserver.org/tinyows/"
         email="tinyows-users@lists.maptools.org" />

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 optional   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’ Yes PostgreSQL Schema name.
table optional   No PostgreSQL table name (default is to use layer’s name).
abstract optional   No Abstract text
keywords optional   Yes 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
include_items optional   Yes Comma separated list of columns to retrieve (only)
exclude_items optional   Yes Comma separated list of columns to not retrieve
pkey optional   Yes Column name to use as a Primary Key, when there’s no PostgreSQL one (e.g useful to use with VIEW)
<tinyows>
 ...
     <layer retrievable="1"
        writable="1"
        ns_prefix="tows"
        ns_uri="http://www.mapserver.org/tinyows/"
        name="world"
        title="World Administrative Boundaries" />
 ...
</tinyows>

Nested Layers

Layer entities could be nested, properties in this case are inherited. A Layer without title is then considered as a ‘virtual’ layer.

<tinyows>
 ...
     <layer name="root"
            retrievable="1" writable="1"
            ns_prefix="tows"
            ns_uri="http://www.mapserver.org/tinyows/"
            schema="my_db_schema">

          <layer name="foo" title="foo" />
          <layer name="bar" title="bar" />

     </layer>

 ...
</tinyows>