Tracker geo databases
Which databases determine a visitor's country, city, provider and connection type, where they come from and how to check their state.
From a visitor's IP, the tracker determines the country, region, city, provider, time zone and connection type. The data comes from geo database files on the server and is used in stream filters, cloaking checks, macros and reports. The owner and the admin can see the state of the databases.
Three databases
The files are on the server in the /opt/micator/data/geoip directory. If you set a different directory with the --path parameter during installation, the data/geoip folder is inside it. In installations made before this release, the default installation directory is /opt/tracker and the Docker Compose project in the commands below is tracker; see names in such installations. The file names are fixed.
| Database | File | What it provides | Where it comes from |
|---|---|---|---|
| DB-IP City Lite, MMDB format | city.mmdb | Country, region, city | Downloaded during installation |
| IP2Location | ip2location.bin | Provider and time zone. Country, region and city — if the first database did not provide them | Placed on the server manually |
| IP2Proxy | ip2proxy.bin | Connection type: data center, VPN, Tor, proxy | Downloaded from the panel with a download token |
The set of IP2Location fields depends on the database package: the tracker does not get a field from it if the file does not contain that field.
Region and city names are written as they are in the database, in English: California, Berlin.
What the installer adds
The installer downloads the free DB-IP City Lite database from download.db-ip.com and saves it as city.mmdb. It first requests the file for the current month and, if that fails, the file for the previous month. If city.mmdb is already in the directory, it is not downloaded again.
After installation, the country, region and city are determined by IP. This database has no provider, time zone or connection type.
The other databases are added separately:
- IP2Proxy is connected in the panel: Settings → Bots and GEO («Настройки → Боты и гео»), the IP2Proxy block. The steps are on the IP2Proxy page.
- IP2Location is added as the
ip2location.binfile; see Replacing and updating the databases.
If the database was not downloaded during installation, see GeoIP database was not downloaded.
How the data is combined
The tracker queries the databases in order and takes each field from the first database where it is filled in.
city.mmdb— country, region, city. The time zone is taken from here only if it is recorded in the file; the database from the installation does not have it.ip2location.bin— the provider and everything left empty after the first database.ip2proxy.bin— connection type. Country and provider are taken from it only if the first two databases did not provide them.
Only IP2Proxy provides the connection type. Values: hosting — data center, vpn, tor, proxy. For a regular connection the value is empty.
A database that failed to open is skipped; the others keep working.
Real IP behind Cloudflare and proxies
When a domain works through Cloudflare or a reverse proxy node, the request reaches the tracker server from the intermediary's address. The tracker takes the visitor's address from the request headers in this order:
CF-Connecting-IP.- The first address in
X-Forwarded-For.
The headers are taken into account only when the request came from Cloudflare or from a reverse proxy node the tracker trusts. When the server is accessed directly, the connection address is used, even if the request contains CF-Connecting-IP. The connection address is also used when none of the headers contains an IP address. The address found is used to determine GEO and connection type, and it is also recorded in the click.
Engine geo databases block
- Open Admin panel → Status («Админ-панель → Состояние»).
- Find the Engine geo databases («Геобазы движка») block.
The block has three columns: mmdb — this is the city.mmdb file, ip2location and ip2proxy. Under the name is the status, and below that the file size and date in the form “file from 04.10.2026” («файл от 04.10.2026»). If there is no file, there is no size and date line either. The data refreshes by itself every 15 seconds; the Refresh («Обновить») button rereads it immediately.
| Status | What it means |
|---|---|
| Loaded («Загружена») | The file is open, and the database is used when processing clicks |
| Open error («Ошибка открытия») | The file is missing from the directory, has no read permission, or cannot be read as a database of this format |
| Not connected («Не подключена») | Status of the ip2proxy column: the database is not loaded. The download progress is shown in the IP2Proxy block; see Status lines |
If there is no ip2location.bin file on the server, the ip2location column shows Open error. This is how an installation without this database looks: the other databases work, and you do not need to do anything.
Instead of the columns, there may be a message:
- “No fresh data from redirect” («Нет свежих данных от redirect») — the information from the click handler is older than 30 seconds. What to check is in the Click intake queue section.
- “The redirect version does not report geo databases yet” («Версия redirect ещё не передаёт сведения о геобазах») — the click handler did not report the state of the databases.
For mmdb and ip2location, the status and date refer to the file the click handler opened at startup. The date is the file's modification date on the server, not the date the provider released the data.
Replacing and updating the databases
| Database | How it is updated | Click handler restart |
|---|---|---|
city.mmdb | Manually: the file is replaced on the server | Required |
ip2location.bin | Manually: the file is placed or replaced on the server | Required |
ip2proxy.bin | From the panel: after a successful download, the next check is in 24 hours; see Update schedule | Not required |
The tracker does not update city.mmdb and ip2location.bin by itself: the directory keeps the file downloaded during installation or placed manually. The click handler — the redirect service — reads these files once at startup, so a new file starts working after a restart.
- Upload the new file to the server into any folder, for example
/root. - Move it into the geo database directory under the name
city.mmdborip2location.bin. The name is written in lowercase. - Allow reading the file.
- Restart the click handler.
- Open Admin panel → Status and check for the Loaded status and the new file date.
Commands for steps 2–4, using city.mmdb as an example:
sudo mv /root/city.mmdb /opt/micator/data/geoip/city.mmdb
sudo chmod 644 /opt/micator/data/geoip/city.mmdb
cd /opt/micator
sudo docker compose --project-name micator --env-file .env.production -f docker-compose.prod.yml restart redirectMove the finished file with the mv command instead of writing it over the old one: the click handler keeps the old file open until it restarts.
While the click handler is restarting, clicks on campaign links are not processed. Restart it when traffic is at its lowest.
The ip2proxy.bin file is updated by the panel; a new version is picked up without a restart.
Geo database files are included in the backup. When you restore on a new server through the first-run wizard, they are put back in place. Keep only database files in the geo database directory, without archives, old versions or subfolders: the wizard will not restore a backup with other files in this directory and will show the message “The backup contains an unsupported geo database file.” («Копия содержит неподдерживаемый файл геобазы.»)
What does not work without a database
The tracker accepts clicks without any of the databases. A field that nothing can determine stays empty. An empty value does not match any value of a condition: a condition with the in list («в списке») operator is not met for such a click, and one with the not in list («не в списке») operator is met.
| What is missing | What stays empty and what it affects |
|---|---|
city.mmdb and ip2location.bin | Region and city. Only IP2Proxy provides the country, if it is connected and knows the address. Affected: the GEO («Гео»), Region («Регион») and City («Город») conditions, the {country}, {region}, {city} macros, the Country («Страна»), Region, City report breakdowns, and the country check in cloaking. The phone mask picks the USA |
ip2location.bin | The provider comes only from IP2Proxy. If neither database is available, the ISP condition with the in list operator is not met, and the {isp} macro is empty. With the city.mmdb database from the installation, there is no time zone by IP: the time zone check in the JS challenge does not count a mismatch |
ip2proxy.bin | Connection type. The Block proxy / VPN / Tor («Блокировать прокси / VPN / Tor») checkbox and the Connection («Коннект») and Proxy / DC («Прокси / ДЦ») conditions do not trigger. The {connection_type} macro is empty. Clicks from data centers are not marked as bots by connection type |
A stream with the GEO condition and the in list operator does not receive clicks whose country was not determined. In a campaign with cloaking, such clicks go to the “white” stream if the countries are set in the target streams; see Where cloaking gets the countries. Before launching traffic, check that mmdb shows the Loaded status.
Frequently asked questions
I replaced the file, but the date in the block is the same
For city.mmdb and ip2location.bin, the block shows the file opened when the click handler started. Restart it; see Replacing and updating the databases.
Do I need to connect all three databases
No. For conditions by country, region and city, the city.mmdb from the installation is enough. IP2Proxy is needed to filter out data centers, proxies and VPNs. IP2Location adds the provider and time zone.