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?

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>