mod_tile and renderd form the classic raster map tile stack powering OpenStreetMap.org:
mod_tile: A high-performance Apache 2 HTTP module that serves map tiles, manages HTTP cache headers and rate limiting, exposes Prometheus metrics, and communicates with a rendering daemon to generate missing or outdated tiles on demand.renderd: A multithreaded rendering daemon that uses Mapnik to render map tiles via a prioritized queuing system.
Alternative Backend: Tirex can be used as a drop-in replacement for
renderdalongsidemod_tile.
- Features & Architecture
- Dependencies
- Installation
- Building from Source
- Quickstart & Configuration
- Command-Line Utilities
- Documentation & Manpages
- Performance
- License
mod_tile extends Apache HTTPD's file-serving pipeline with map-specific capabilities:
- On-Demand Rendering & Expiry: Detects missing (
tileMissing) or stale (tileOld,tileVeryOld) tiles by comparing tile modification times against planet database import timestamps (/planet-import-complete), and requests rendering or re-rendering fromrenderd. Supports/statusand/dirtyURL suffixes (ModTileEnableStatusURL,ModTileEnableDirtyURL) for inspecting freshness or manually triggering background re-renders. - Smart HTTP Caching: Computes HTTP
Cache-Control(max-age) andExpiresheaders using configurable zoom-level minimums (ModTileCacheDurationLowZoom,ModTileCacheDurationMediumZoom,ModTileCacheDurationMinimum), tile modification age (ModTileCacheLastModifiedFactor), dirty-tile lifetimes (ModTileCacheDurationDirty), extended-cache hostname rules (ModTileCacheExtendedHostName), randomized jitter to prevent cache stampedes, andModTileCacheDurationMax. Emits MD5ETagheaders with HTTP304 Not Modifiedconditional response handling. - Dynamic URL Parameterization: Supports runtime style adjustments via URL path segments before
/{z}/{x}/{y}.{ext}(configured viaparameterize_styleinrenderd.confand cached per option string inrenderd):language: Dynamically localizes map labels (e.g.,/tiles/layer/en,de,_/0/0/0.png).toggle_layer: Dynamically enables or disables Mapnik layers (e.g.,/tiles/layer/-layer1,-layer2,+layer2/0/0/0.png).
- TileJSON & CORS Support: Automatically serves TileJSON 2.0.0 layer metadata at
{URI}/tile-layer.json(including attribution, description, zoom bounds, and server aliases) and supports per-layer Cross-Origin Resource Sharing (cors) headers. - Pluggable Storage Backends: Supports local POSIX filesystems (
/...), Ceph RADOS object stores (rados://...), Memcached (memcached://...), read-only HTTP/HTTPS upstream tile proxies (ro_http_proxy://...), Cairo-backed read-only composite layers (composite:{...}), and a no-op null backend (null://...) for benchmarking. - Traffic Control & Load Shedding: Built-in per-IP token-bucket rate limiting (
ModTileEnableTileThrottling,ModTileThrottlingTiles,ModTileThrottlingRenders) withX-Forwarded-Forproxy support (ModTileEnableTileThrottlingXForward), plus 1-minute system load shedding (ModTileMaxLoadOlddefault16,ModTileMaxLoadMissingdefault50). - Metrics & Monitoring: Exposes native Prometheus metrics at
/metricsand plain-text server statistics at/mod_tile(HTTP status counts, cache hit/miss/render outcomes, per-zoom request/latency counters, and per-layer totals) controlled byModTileEnableStats.
- Prioritized Multithreaded Queuing: Listens on a UNIX domain socket (
/run/renderd/renderd.sock) or TCP port (default7654) using a versioned binary IPC protocol (PROTO_VER = 3, backwards-compatible with v1/v2). Coalesces duplicate concurrent requests for the same metatile and processes jobs across five queues in strict priority order:reqPrio(cmdRenderPrio): High-priority on-the-fly rendering for missing tiles (capped atREQ_LIMIT = 256).req(cmdRender): Standard-priority on-the-fly rendering, including heavily expired tiles exceedingModTileVeryOldThreshold(default 365 days; capped atREQ_LIMIT = 256).reqLow(cmdRenderLow): Low-priority on-the-fly re-rendering for expired (tileOld) tiles (capped atREQ_LIMIT = 256).dirty(cmdDirty): Background queue for asynchronous expiry requests and overflow from saturated interactive/bulk queues (capped atDIRTY_LIMIT = 8000).reqBulk(cmdRenderBulk): Lowest-priority queue for batch pre-rendering (render_list,render_expired, orModTileBulkMode On; capped atREQ_LIMIT = 256).
- Flexible Mapnik Rendering: Supports custom tile dimensions (
tilesize, default256px), HiDPI/Retina scale factors (scalefrom0.1to8.0), multiple image writers (png256,png32,jpeg,webp), automatic datasource connection pool scaling (max_size = num_threads + 2whennum_threads > 10), and built-in projection handling for Web Mercator, Plate Carrée (+proj=eqc), and British National Grid (OSGB36). - HTCP Cache Invalidation: Sends RFC 2756 HTCP
CLRUDP purge datagrams (default UDP port4827) to upstream caching proxies configured viahtcphostwhenever metatiles are rendered and saved. - Distributed Rendering & Runtime Stats: Scales horizontally across multiple machines using a master/slave architecture (
renderd --slaveand[renderd0]–[renderd4]sections inrenderd.conf, up toMAX_SLAVES = 5) and optionally dumps periodic queue/render statistics tostats_file.
When using the default POSIX filesystem storage backend (store_file.c), renderd groups an 8×8 grid (64 tiles) into a single metatile .meta archive stored in a bitwise-interleaved directory hierarchy (DIRECTORY_HASH) to avoid inode exhaustion and directory bottlenecks from millions of tiny image files:
/[base_dir]/[TileSetName]/[Z]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy].meta
base_dir: Configurable tile cache root (default:/var/cache/renderd/tiles).TileSetName: Map section name defined in/etc/renderd.conf.Z: Zoom level (0–20by default viaMAX_ZOOM, up to30viaMAX_ZOOM_SERVER/AddTileConfig).[xxxxyyyy]: 8-bit directory hashes interleaving 4 bits of the X coordinate and 4 bits of the Y coordinate, clustering 16×16 metatiles per subdirectory.
Apache transparently maps incoming standard tile requests (/[TileSetName]/{Z}/{X}/{Y}.{ext}) to the corresponding metatile offset.
- Operating Systems: GNU/Linux, FreeBSD, OpenBSD, macOS
- Build Systems: CMake (recommended), GNU Autotools (deprecated)
| Dependency | Required | Description |
|---|---|---|
| Apache HTTP Server | Yes | Web server (httpd / apache2 dev headers, APR, APXS) |
| Mapnik | Yes | Map rendering engine (libmapnik, Mapnik 3 or 4) |
| ICU | Yes | International Components for Unicode (libicu, linked into renderd) |
| GLib | Yes | Core utility library (libglib-2.0) |
| iniParser | Yes | Configuration file parser for renderd.conf (libiniparser) |
| Cairo | Optional | Read-only composite tile storage backend (libcairo) |
| cURL | Optional | HTTP/HTTPS proxy tile storage backend (libcurl) |
| Memcached | Optional | Memcached tile storage backend (libmemcached) |
| RADOS | Optional | Ceph RADOS object tile storage backend (librados) |
Custom malloc (MALLOC_LIB) |
Optional | Alternate allocator (e.g., jemalloc/tcmalloc; defaults to libc) |
Pre-built packages are available on Debian 11 (Bullseye)+ and Ubuntu 21.04 (Hirsute Hippo)+ (maintained by the Debian GIS Team in their packaging repository):
sudo apt update
sudo apt install libapache2-mod-tile renderdIf you are developing mod_tile or running on a distribution without pre-built packages, follow the step-by-step build guides for your OS:
Docker & CI: A Docker-based build and test environment is available in
/docker. For exact build flags and dependency setups, see our GitHub Actions CI workflow.
Sample configuration files are located in etc/, and a self-contained test map is included in utils/example-map/. (Note: Paths below assume Debian/Ubuntu conventions and may vary by distribution.)
- Copy the example map data:
sudo mkdir -p /usr/share/renderd
sudo cp -av utils/example-map /usr/share/renderd/- Install the example Apache virtual host configuration:
sudo cp -av etc/apache2/renderd-example-map.conf /etc/apache2/sites-available/renderd-example-map.conf- Register the example map layers in
/etc/renderd.conf(supports up toXMLCONFIGS_MAX = 100map sections; trailing slashes are appended automatically toURIvalues, and any parent URI prefix must be listed after more specific child URI paths):
cat << 'EOF' | sudo tee -a /etc/renderd.conf
[example-map]
URI=/tiles/renderd-example
XML=/usr/share/renderd/example-map/mapnik.xml
[example-map-jpg]
TYPE=jpg image/jpeg jpeg
URI=/tiles/renderd-example-jpg
XML=/usr/share/renderd/example-map/mapnik.xml
[example-map-png256]
TYPE=png image/png png256
URI=/tiles/renderd-example-png256
XML=/usr/share/renderd/example-map/mapnik.xml
[example-map-png32]
TYPE=png image/png png32
URI=/tiles/renderd-example-png32
XML=/usr/share/renderd/example-map/mapnik.xml
[example-map-webp]
TYPE=webp image/webp webp
URI=/tiles/renderd-example-webp
XML=/usr/share/renderd/example-map/mapnik.xml
EOF- Ensure the runtime socket directory exists and start
renderd:
sudo mkdir -p /run/renderd
sudo renderd- Enable the Apache module, site configuration, and restart Apache:
sudo a2enmod tile
sudo a2ensite renderd-example-map
sudo apache2ctl restart- Verify the setup by opening the interactive example map or requesting a single tile:
- Slippy map viewer:
http://localhost:8081/renderd-example-map - Single tile (
z=0, x=0, y=0):http://localhost:8081/tiles/renderd-example/0/0/0.png
Full Planet / Production Setup: For complete instructions on setting up a production OpenStreetMap tile server with PostgreSQL, PostGIS, and
osm2pgsql, see the switch2osm serving tiles guide.
In addition to renderd and mod_tile.so, this repository builds several CLI tools for cache management and benchmarking:
| Command | Purpose |
|---|---|
renderd |
The core tile rendering daemon (-f for foreground debugging, -c for custom config, -s for slave index). |
render_list |
Pre-renders tiles from an X Y Z list on STDIN or across a zoom, tile-coordinate (--min-x/--max-x/--min-y/--max-y), or WGS84 lat/lon bounding-box range (--all), skipping cached metatiles unless --force is given. |
render_expired |
Reads a z/x/y list of modified tiles on STDIN (e.g., from osm2pgsql), expands ancestor metatiles across zoom levels, and deletes (--delete-from), marks expired (--touch-from), or re-renders them. |
render_speedtest |
Benchmarks rendering throughput across zoom levels against a running renderd instance. |
render_old |
Pre-renders expired/outdated tiles by submitting requests to renderd. |
Detailed reference documentation for all directives, INI options, and CLI flags is provided in the repository's manpages (in docs/man/):
mod_tile(5)— Apache HTTPD configuration directives (AddTileConfig,LoadTileConfigFile, caching durations, socket timeouts, throttling).renderd(1)— Rendering daemon CLI flags and master/slave operation.renderd.conf(5)— INI sections ([renderd],[mapnik], and map layer options includingparameterize_style,scale,tilesize,htcphost, andtype).render_list(1),render_expired(1),render_speedtest(1),render_old(1)— CLI utility usage and options.
- Serving (
mod_tile): Engineered for high-concurrency static/cached delivery. Given adequate disk I/O or page-cache memory, a single server can sustain >10,000 tiles/second. - Rendering (
renderd): Rendering throughput depends primarily on PostGIS database query performance and Mapnik stylesheet complexity.renderdscales linearly across multi-core CPUs (num_threads=-1auto-detects online CPU core count viasysconf(_SC_NPROCESSORS_ONLN)) and supports multi-server master/slave clusters for heavy rendering workloads.
Copyright © 2007–2026 by mod_tile contributors (see AUTHORS).
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.
See COPYING for the full license text.
