Modules

In Egern, modules are preset configuration snippets that allow users to conveniently enable or disable a specific set of network processing rules. Modules cover a wide range of functionality and can include rules, URL rewrites, header rewrites, body rewrites, Map Local, scripts, MITM, HTTP captures, and panels. When a module is enabled, its configuration is merged into Egern's main configuration.

Module Reference Configuration

Referencing modules in the main configuration file:

• name (string), optional

  The display name of the module, overriding the name defined within the module file. When not set, the name field from the module file or the URL is used.

• url (string), required

  The address of the module file, which can be a local file path or a remote URL.

• compat_arguments (object), optional

  Arguments passed to the module, used to override the default argument values defined in the module file. Arguments are substituted as variables when the module is parsed.

• update_interval (integer), optional

  When the module file is a remote URL, this parameter specifies the update interval (in seconds) for the module. The default value is 86400 (24 hours).

• enabled (boolean), optional

  Controls whether the module is enabled. The default value is true.

Configuration Example

modules:
  - name: "Ad Blocking"
    url: "https://example.com/adblock.yaml"
    enabled: true
    update_interval: 86400
  - url: "https://example.com/custom.yaml"
    compat_arguments:
      API_KEY: "your_api_key"
      REGION: "cn"

Module File Format

A module file itself is a YAML-formatted file containing metadata and configuration content.

Metadata Fields

• name (string), optional

  Module name.

• description (string), optional

  Module description.

• author (string), optional

  Module author.

• homepage (string), optional

  Module homepage URL.

• manual (string), optional

  Usage instructions URL.

• icon (string), optional

  Module icon, supporting SF Symbols names or URLs.

• open_url (string), optional

  URL to open the settings page.

• compat_arguments (object), optional

  Default values for module arguments.

• compat_arguments_desc (string), optional

  Documentation for module arguments.

Configuration Content Fields

A module file can contain the following configuration items, which are merged with the main configuration:

• dns (object), optional

  DNS configuration.

• rules (array), optional

  Rule list.

• url_rewrites (array), optional

  URL rewrite list.

• header_rewrites (array), optional

  Header rewrite list.

• body_rewrites (array), optional

  Body rewrite list.

• map_locals (array), optional

  Map Local list.

• scriptings (array), optional

  Script list.

• mitm (object), optional

  MITM configuration.

• http_captures (array), optional

  HTTP capture hostname list.

• panels (array), optional

  Panel list.

• bypass_tunnel_proxy (array), optional

  List of domains that bypass the tunnel proxy.

• real_ip_domains (array), optional

  List of domains that use real IP addresses (instead of Fake IP).

Configuration Example

name: "Ad Blocking Module"
description: "Filters common ads and trackers"
author: "module-author"
homepage: "https://github.com/example/adblock-module"
icon: "shield.fill"

compat_arguments:
  BLOCK_MODE: "reject"

rules:
  - domain_suffix:
      match: "ad.example.com"
      policy: REJECT

url_rewrites:
  - match: "^https://ads\\.example\\.com"
    location: "https://reject/"
    status_code: 307

mitm:
  hostnames:
    - "*.example.com"

panels:
  - name: adblock-info
    title: Ad Blocking
    content: "Ad blocking is enabled"
    icon: shield.fill