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.2.0
 FCGI support:      Yes
 Config File Path:  /etc/tinyows.xml (TinyOWS XML)
 PostGIS Version:   3.1.1
 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?	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?	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>