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.
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||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.|
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.|
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!).|
|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').|
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
- These variables are defined in Tirex.pm with the default setting and are used throughout the Perl code.