English | Русский

Amnezia Split Tunneling

TL;DR

Download the ready-to-use RU direct IP list

A Node.js CLI that generates an ip-list.json file for AmneziaVPN split tunneling.

The default ru-direct profile combines Russian IPv4 networks from MaxMind GeoLite2 with local networks. IPdeny is used as a fallback. The generated list is intended to route this traffic outside the VPN tunnel.

Requirements

• Node.js 20.12 or newer;
• npm;
• a free MaxMind account and GeoLite2 license key for the primary GeoIP source;
• access to MaxMind or the fallback www.ipdeny.com source when refreshing the cache.

Installation

Install the dependencies:

npm install

Create a local npm link to make amnezia-split available as a command:

npm link

You can now run:

amnezia-split list
amnezia-split build ru-direct

Without npm link, invoke the CLI through Node.js:

node ./src/cli.js list
node ./src/cli.js build ru-direct

Run these commands from the project root unless you provide an explicit configuration path.

Listing profiles

amnezia-split list

Use a different configuration file:

amnezia-split list --config ./configs/custom.yaml

Building a list

amnezia-split build ru-direct

The default output path is:

dist/ru-direct.ip-list.json

The file contains IPv4 networks in the AmneziaVPN import format:

[
  { "hostname": "2.56.24.0/22", "ip": "" },
  { "hostname": "10.0.0.0/8", "ip": "" }
]

A plain JSON array of strings cannot be imported: AmneziaVPN expects every entry to contain the hostname and ip fields.

Importing the list into AmneziaVPN

Disconnect from the VPN and run amnezia-split build ru-direct, then import the generated file:

1. On the AmneziaVPN home screen, click Split tunneling disabled.

   

2. Open Site-based split tunneling.

   

3. Select Addresses from the list should not be accessed via VPN. Russian and local networks from the generated list will then bypass the VPN.

   

4. Open the additional actions menu and click Import.

   

5. Select Replace site list to replace the current address list.

   

6. Open the project dist directory and select ru-direct.ip-list.json.

   

7. Verify that the addresses appear in the list, enable Split tunneling, return to the home screen, and connect to the VPN.

   

Build options

Set the output JSON path:

amnezia-split build ru-direct --out dist/ip-list.json

Also write a plain-text list with one network per line:

amnezia-split build ru-direct --txt dist/ru-direct.txt

Generate a report showing the source of every network:

amnezia-split build ru-direct --explain dist/ru-direct.explain.txt

Options can be combined:

amnezia-split build ru-direct \
  --out dist/ru-direct.ip-list.json \
  --txt dist/ru-direct.txt \
  --explain dist/ru-direct.explain.txt

Ignore the existing cache and download fresh data:

amnezia-split build ru-direct --no-cache

Use a different configuration file:

amnezia-split build custom-profile --config ./configs/custom.yaml

Show all available options:

amnezia-split build --help

Configuration

By default, the CLI reads amnezia-split.yaml from the current directory:

profiles:
  ru-direct:
    description: "RU and local/private networks bypass VPN"
    mode: bypass-vpn
    include:
      - geoip:ru
      - geoip:private
    # Keep this address inside the VPN even if it belongs to geoip:ru.
    exclude:
      - cidr:203.0.113.10/32
    # Domains are resolved to their current IPv4 addresses during the build.
    domains:
      - gosuslugi.ru

sources:
  geoip:
    provider: maxmind
    fallbackProvider: ipdeny
    maxmind:
      cacheTtlHours: 168
    ipdeny:
      aggregated: true
      cacheTtlHours: 24
  url:
    cacheTtlHours: 24
  dns:
    cacheTtlHours: 1

Profile fields:

• description — text displayed by the list command;
• mode — the profile purpose displayed in the console and explain report;
• include — rules used to build the list;
• exclude — networks to subtract from the result;
• domains — domains whose current IPv4 addresses should be added as /32 routes.

The mode field does not change the output format. Select whether listed traffic uses or bypasses the VPN in the AmneziaVPN split tunneling settings.

Supported rules

• geoip:ru — country IPv4 networks using a two-letter country code, such as geoip:kz or geoip:de;
• geoip:private — LAN, CGNAT, link-local, and multicast IPv4 networks;
• geoip:special — loopback, documentation, benchmark, and reserved IPv4 networks;
• cidr:192.0.2.0/24 — one explicit network;
• file:rules/custom.txt — CIDRs from a local text file;
• url:https://example.org/networks.txt — CIDRs from a remote text file;
• domain:example.org — the domain's current A records as /32 routes.

A local or remote list must contain one CIDR per line. Empty lines and lines beginning with # are ignored:

# Corporate networks
192.0.2.0/24
198.51.100.10/32

Relative file: paths are resolved from the directory containing the YAML configuration file.

Every rule type can be used in both include and exclude. Exclusion also works for an address inside a larger network: for example, the VPN server's /32 route is correctly subtracted from its containing geoip:ru range.

Domains

Domains can be listed in a separate profile field:

profiles:
  ru-services:
    include:
      - geoip:private
    domains:
      - avito.st
      - gosuslugi.ru
      - esia.gosuslugi.ru

The build performs IPv4 DNS lookups. Resolved addresses are cached and added as /32 routes.

This is not a complete equivalent of V2Ray geosite: AmneziaVPN routes IP addresses and does not evaluate the domain name on every connection. CDN addresses may change or be shared by unrelated sites, so domain rules work best for a small set of important services with regular profile rebuilds.

Source settings

• provider — primary GeoIP provider; defaults to maxmind;
• fallbackProvider — provider used when the primary source is unavailable; defaults to ipdeny;
• sources.geoip.maxmind.cacheTtlHours — MaxMind cache lifetime; defaults to 168 hours;
• sources.geoip.ipdeny.aggregated — use aggregated IPdeny lists; defaults to true;
• sources.geoip.ipdeny.cacheTtlHours — IPdeny cache lifetime; defaults to 24 hours;
• sources.url.cacheTtlHours — remote CIDR-list cache lifetime; defaults to 24 hours;
• sources.dns.cacheTtlHours — DNS cache lifetime; defaults to 1 hour.

MaxMind GeoLite2

Create a free MaxMind account and license key. Copy the environment template:

cp .env.example .env

Fill in .env:

MAXMIND_ACCOUNT_ID=your-account-id
MAXMIND_LICENSE_KEY=your-license-key

The CLI loads .env from the current directory automatically:

amnezia-split build ru-direct

The .env file is ignored by Git. Credentials are never written to the cache or output files. When MaxMind cannot be downloaded and no fresh MaxMind cache exists, the build automatically falls back to IPdeny and prints a warning. The same warning is included in the --explain report.

Custom profile example

profiles:
  kz-direct:
    description: "Kazakhstan and local networks bypass VPN"
    mode: bypass-vpn
    include:
      - geoip:kz
      - geoip:private

Build it with:

amnezia-split build kz-direct

Cache

Downloaded lists are stored in .cache/maxmind, .cache/ipdeny, and .cache/url; DNS results are stored in .cache/dns. A build does not require network access while its cached data remains fresh.

The --no-cache option disables cache reads. Successfully downloaded and validated data is still written for future builds.

Tests

Run the automated tests:

npm test

Build the default profile through npm:

npm run build:ru