Tirex/Config

Typical Config File Hierarchy:

/etc/tirex
/etc/tirex/tirex.conf
/etc/tirex/renderer
/etc/tirex/renderer/test
/etc/tirex/renderer/test/checkerboard.conf
/etc/tirex/renderer/test.conf
/etc/tirex/renderer/mapnik
/etc/tirex/renderer/mapnik.conf
/etc/tirex/renderer/mapnik/default.conf
/etc/tirex/renderer/mapnik/example.conf
 /etc/tirex/renderer/wms
/etc/tirex/renderer/wms.conf
/etc/tirex/renderer/wms/demowms.conf

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	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:

name=name

The name of the bucket, for display purposes.

minprio=minprio

A request with priority minprio or higher is put in this bucket, unless it fits in another bucket with a higher minprio.

maxload=maxload

This bucket only takes requests if the system load is not more than maxload.

maxproc=maxproc

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.