From OpenStreetMap Wiki
Jump to navigation Jump to search

Typical Config File Hierarchy:


The Tirex system uses several config files. By default they all are in the /etc/tirex directory. You can change this directory by using the command line option --config on almost all Tirex commands.

You can check the validity of your configuration with the tirex-check-config command. It will output errors and warnings. Note that it currently only checks the main config file and not the renderer and main config.

Common format

All config files share a common format. They are read line by line. Empty lines and everything after a # are ignored. The rest of the lines contain settings in the form key=value.

Main config file: tirex.conf

The main config file is named tirex.conf. It is read by many Tirex commands. There are sensible defaults for nearly all settings. To get started you only need to define one or more bucket options.

Config option Perl default variable[1] Default setting Description
metatile_columns $Tirex::METATILE_COLUMNS 8 The number of tile columns in a metatile. See below.
metatile_rows $Tirex::METATILE_ROWS 8 The number of tile rows in a metatile. See below.
stats_dir $Tirex::STATS_DIR /var/lib/tirex/stats The directory where statistics files are generated/expected by the tirex-tiledir-* commands. This must be writeable by the tirex user.
socket_dir $Tirex::SOCKET_DIR /var/run/tirex The directory where UNIX domain sockets are generated/expected. (Currently this is only one socket for the master called master.sock). This must be writeable by the tirex user. The modtile_socket_name (see below) does not have to be in this directory.
modtile_socket_name $Tirex::MODTILE_SOCK /var/lib/tirex/modtile.sock The UNIX domain socket where requests from mod_tile are read. Must be the same as the ModTileRenderdSocketName in your Apache config.
master_pidfile $Tirex::MASTER_PIDFILE /var/run/tirex/tirex-master.pid The master writes its process ID into this file. Must be writable for the tirex user.
master_syslog_facility $Tirex::MASTER_SYSLOG_FACILITY daemon Syslog facility used in tirex-master.
master_logfile $Tirex::MASTER_LOGFILE /var/log/tirex/jobs.log Logfile where all rendered jobs are logged. Must be writable for the tirex user.
master_rendering_timeout $Tirex::MASTER_RENDERING_TIMEOUT 10 If the rendering of a metatile takes more than this many minutes the master gives up on it and removes the job from the list of currently rendering tiles. This must be larger than backend_manager_alive_timeout and should be larger than the rendering of any tile can need. Its only used to make sure that a rendering process that is long gone doesn't take up resources forever.
backend_manager_pidfile $Tirex::BACKEND_MANAGER_PIDFILE /var/run/tirex/tirex-backend-manager.pid The tirex-backend-manager writes its process ID into this file. Must be writable for the tirex user.
backend_manager_syslog_facility $Tirex::BACKEND_MANAGER_SYSLOG_FACILITY daemon Syslog facility used by tirex-backend-manager.
backend_manager_alive_timeout $Tirex::BACKEND_MANAGER_ALIVE_TIMEOUT 8 If a rendering process doesn't send an alive message in this many minutes to the backend-manager, it will be killed by the manager. Make this smaller than master_rendering_timeout.
syncd_pidfile $Tirex::SYNCD_PIDFILE /var/run/tirex/tirex-syncd.pid The tirex-syncd process writes its process ID into this file. Must be writable for the tirex user.
syncd_udp_port $Tirex::SYNCD_UDP_PORT 9323 UDP port where the tirex-syncd listens for messages from master. Normally there is no reason to change this.
syncd_aggregate_delay $Tirex::SYNCD_AGGREGATE_DELAY 5 If no tiles are available to synchronize, syncd will sleep this many seconds before checking again.
syncd_command $Tirex::SYNCD_COMMAND too long! Command to synchronize tiles. May contain %HOST% and %TILES% which will be replaced by the hostname and a space-separated list of tiles. The suggested mode of operatio is to employ a combination of tar+ssh to wrap tiles into a tar archive, ssh to remote machine, and unwrap there. A persistent ssh master connection can be used to minimise connection setup overhead.
sync_to_host none none If this is defined, the tirex-syncd will copy rendered tiles to this server. If this is not defined the tirex-syncd will not start. A comma or space separated list of hosts is allowed.
bucket none none Used a different format, see below.

Bucket configuration

The bucket config option may appear multiple times, and each occurrence defines one priority bucket for executing render requests. At least one such option must be present, and each bucket option must have the following parameters:

The name of the bucket, for display purposes.
A request with priority minprio or higher is put in this bucket, unless it fits in another bucket with a higher minprio.
This bucket only takes requests if the system load is not more than maxload.
A request can only be added to this bucket if the total number of requests in all buckets is less than maxproc.

Here is an example for a typical bucket setup:

bucket name=live       minprio=1  maxproc=4 maxload=20
bucket name=important  minprio=10 maxproc=3 maxload=8
bucket name=background minprio=20 maxproc=2 maxload=4

The bucket live takes up to 4 requests of priority 1 to 9 and is avilable at system loads up to 20. The bucket important takes up to 3 requests of priority 10 to 19 and is available at system loads up to 8. The background bucket takes only 2 requests of priority 20 or higher and is only available at system loads up to 4. This setup guarantees that at least one request with priority 1 to 9 can always be added even if the system is constantly battered with requests of priority 10.

Requests from mod_tile for non-existing tiles will normally arrive with priority 1, sometimes mod_tile will send requests with priority 10 for existing tiles that need re-rendering.

Renderer Config Files

For each renderer backend you need one config file in the directory /etc/tirex/renderer named something.conf. It is usually named after the backend, for instance mapnik, but it doesn't have to be. You can have several renderer config files for the same backend, if you want to start the backend several times, each with different settings.

Each config file contains the following settings:

Config option Default setting Description
name none Name of this renderer. Use only [a-z0-9_]-
path none Path to executable of backend, usually this is /usr/lib/tirex/backends/backend-name.
port none The UDP port where this renderer can be contacted. Must be different from all other renderers and >1024.
procs none Number of processes that should be started with this configuration. This should generally be as large as the largest maxproc setting of the buckets.
syslog_facility daemon Syslog facility this renderer should log into.
debug 0 (off) Set to '1' to enable debugging.

Depending on the backend there might be more settings.

For the mapnik backend you need to set the following:

Config option Default setting Description
plugindir none Directory with input plugins for mapnik.
fontdir none The directory where the Mapnik rendering engine loads its TrueType fonts from. If the style sheet references fonts that are not present here, the renderer will throw an exception.
fontdir_recurse 0 Set this to 1 if you want fonts loaded recursively from directories inside the fontdir directory.

Map Config Files

For each renderer you have a directory named after the renderer in /etc/tirex/renderer/. It contains one or more map configs. Each has the following config options:

Config option Default setting Description
name none Symbolic name of this map.
tiledir none Directory where tiles for this map are stored. Must be writable for tirex user.
minz 0 Minimum zoom level allowed.
maxz 17 Maximum zoom level allowed.
maxrequests -1 Maximum number of requests until a worker process is restarted.
mapfile none The mapnik .xml file (in case of mapnik renderer)

For some backends there are more backend specific settings:

Backend Config option Default setting Description
test sleep 0 Sleep time after each rendering to simulate longer rendering times.
mapnik buffersize -1 passed as buffer-size to mapnik (in short: this sets how many pixels around the actual image get rendered. Set this higher to reduce rendering artefacts like cut shields or text at the edges of tiles)
mapfile none Name of the Mapnik map configuration XML file.
scalefactor 1.0 passed as scalefactor to mapnik. This can be used to generate HD tiles, e.g. by setting scalefactor to 2.0 and tilesize to 512.
tilesize 256 The size of one tile (not metatile!).
imagetype Image type, directly handed over to Mapnik. Supported values depend which image libraries your Mapnik library was linked to during build. It may support png24 or png32 for truecolor PNG, png8 or png256 for paletted PNG, jpeg80 for JPEG with quality 80, jpegNN for JPEG with quality NN, tiff for TIFF, and webp for WEBP.
wms url none The URL prefix for the WMS server, should probably end with a '?' or '&'.
layers none Comma separated list of layers for the WMS request.
srs EPSG:3857 You need to use the Pseudo-Mercator projection used by OpenStreetMap, Google, etc. here. This was sometimes called 900913, for a short time it was 3785, but the current (May 2010) official EPSG number is 3857. It depends on the WMS server whether it already uses the official number. Hint: the projection OSM (and the others mentioned before) uses is based on a sphere and therefore not identical with what EPSG calls EPSG:3857 which is based on an ellipsoid
transparent FALSE Set TRANSPARENT option on WMS request (can be 'TRUE' or 'FALSE').

Metatile size

There are config options for setting the size of the metatiles (metatile_columns and metatile_rows), ie how many tiles make up a metatile. But those settings are not read by every part of the Tirex system. And there might be some other places with subtle dependencies on the metatile size. The default size of 8x8 works fine. If you want to change the metatile size be aware that you might have to change things here and there. Patches welcome.

Notes and references

  1. These variables are defined in Tirex.pm with the default setting and are used throughout the Perl code.