Skip to content

Modules ​

A module is a TOML file that Specola merges on top of a profile when the profile loads. Use modules for changes you want in several profiles, or want to keep apart from a profile you replace from time to time: your own rules, a home proxy, extra DNS hosts.

text
profiles/
├── work.toml              the profile
├── work.toml.modules      "home-lan.toml" — the modules work.toml applies
└── modules/
    └── home-lan.toml      the module

A module is written like a profile, but contains only what it adds or changes:

toml
# modules/home-lan.toml
[[proxy]]
name = "home"
type = "socks5"
server = "nas.example.org"
port = 1080

[route]
rules = [
  "DOMAIN-SUFFIX,home.arpa,DIRECT",
  "DOMAIN-SUFFIX,media.example.org,home",
]

[dns]
hosts = { "nas.home.arpa" = "192.168.1.10" }

This file is a fragment: it only loads merged into a profile that ends its rules with FINAL.

Using modules in the app ​

On Profiles, select a profile. The Modules list shows every module in the modules folder.

  • New module creates an empty module file. The name you enter becomes the file name (Home LAN becomes Home LAN.toml).
  • Switch a module on to apply it to the selected profile. Drag modules to change the merge order: modules apply from top to bottom, and later ones override earlier ones.
  • Apply and reload saves the list. If the profile is active, it is reloaded.
  • Open the module file opens it in your editor. On Rules, the rules of a module can also be edited and switched off; they are listed before the profile's own rules and labelled with the module's name.
  • Delete module moves the file to modules/.removed/ and takes it off every profile's list.

A module created in the app starts with a [metadata] table holding its display name. Core ignores [metadata] in modules; only the app reads name for display.

Using modules by hand ​

  1. Create the folder modules inside the Profiles folder and put the module file in it.

  2. Create <profile file name>.modules next to the profile, for example work.toml.modules, with one module file name per line, in merge order:

    text
    home-lan.toml
    my-rules.toml
  3. Activate the profile again.

The Profiles folder is listed in Quick Start.

Rules for the list file:

  • Each line is a file name in modules/. It must end in .toml, must not start with ., and must not contain /, \ or :. Lines that break these rules are skipped, and so are repeated names. There is no comment syntax.
  • A listed module whose file is missing is skipped with the warning Module '<name>' is missing; it was skipped.
  • A module that is not valid TOML stops the profile from loading: Module '<name>': <error>.
  • An empty list, or no list file, applies no modules.

The same module can be listed by any number of profiles.

How a module is merged ​

Modules are applied one after another, in list order, each on top of the result so far. Then the result is loaded like a single profile file.

WhatHow it merges
[[proxy]]by name: a module proxy with the name of an existing one replaces it as a whole, in place; a new name is added at the end
[[proxy-group]]by name, the same way
[route] rule-setby name, the same way
[route] rulesthe module's rules are put before the rules so far
tables ([general], [dns], [route], [sniffer], [enhanced-mode], and tables inside them such as dns.listener, dns.hosts, enhanced-mode.tun)key by key; a key the module sets replaces the one before
any other array (bypass, nameserver-proxy, routes, protocols …)replaced as a whole
any other valuereplaced
[metadata], module, modules at the top of a moduleignored

What follows from these rules:

  • Later modules win. A later module overrides the values of earlier ones, and its rules come first, so with first-match order they also take precedence. With the list a.toml, b.toml, the rules end up in the order: b's rules, a's rules, the profile's rules.
  • A proxy, group or rule set is replaced whole. To change one field of a profile's proxy, the module must repeat the complete proxy.
  • Tables merge, arrays do not. dns.hosts entries of a module are added to the profile's; a module's bypass list replaces the profile's list.
  • Module files may write proxies as an array, proxies = [ { name = "...", ... } ], instead of [[proxy]] tables. Do not use both in one file.

Pitfalls ​

  • Do not put FINAL in a module that is applied to a profile with rules. The module's rules go first, so its FINAL lands in the middle and the profile fails with FINAL must be the last rule.
  • Names must stay unique. A module proxy named like a profile's group, or the other way round, fails validation. Use the same name only when you mean to replace.
  • Relative paths resolve from the profile's folder, not from modules/. A local rule set in a module written as path = "rule-sets/mine.txt" is looked up next to the profile, then in the data folder, then in resources/ next to Core.
  • The merged result is checked as a whole. Unknown keys, a rule pointing at an unknown proxy, or a section Core does not accept fail the profile, wherever they came from. The error does not say which file the bad line is in.
  • Changes take effect on activation. Editing a module, or the list, does nothing to the running Core until the profile is activated again. The reload is applied in place, like any profile change.
  • Switched-off rules (<profile>.disabled-rules) are matched by rule text, so they also apply to module rules with the same text.

Checking the merged result ​

--test-config merges modules exactly like activation does:

bash
specola-core --test-config --config work.toml

A missing module shows up as the warning Config: Module '...' is missing; it was skipped in the log output. To see the final rule order, open Rules in the app after activating the profile.

See also Rules, Proxies, and Providers for reusing proxies and rule lists.