adguardhome-sync/README.md

[![Go](https://github.com/bakito/adguardhome-sync/actions/workflows/go.yml/badge.svg)](https://github.com/bakito/adguardhome-sync/actions/workflows/go.yml)
[![e2e tests](https://github.com/bakito/adguardhome-sync/actions/workflows/e2e.yaml/badge.svg)](https://github.com/bakito/adguardhome-sync/actions/workflows/e2e.yaml)
[![Go Report Card](https://goreportcard.com/badge/github.com/bakito/adguardhome-sync)](https://goreportcard.com/report/github.com/bakito/adguardhome-sync)
[![Coverage Status](https://coveralls.io/repos/github/bakito/adguardhome-sync/badge.svg?branch=main&service=github)](https://coveralls.io/github/bakito/adguardhome-sync?branch=main)

# AdGuardHome sync

Synchronize [AdGuardHome](https://github.com/AdguardTeam/AdGuardHome) config to replica instances.

## FAQ

Please check the wiki for [FAQ](https://github.com/bakito/adguardhome-sync/wiki/FAQ).

## Deprecation of Environment Variables as of v0.6.0

The following environment variables have been deprecated and replaced with better readable ones:
Deprecated variables are still supported but will be logged as warning.
| Deprecated | Replacement |
| :----------- |:----------- |
| RUNONSTART | RUN_ON_START |
| PRINTCONFIGONLY | PRINT_CONFIG_ONLY |
| CONTINUE_ON_ERROR | CONTINUE_ON_ERROR |
| API_DARKMODE | API_DARK_MODE |
| FEATURES_DHCP_SERVERCONFIG | FEATURES_DHCP_SERVER_CONFIG |
| FEATURES_DHCP_STATICLEASES | FEATURES_DHCP_STATIC_LEASES |
| FEATURES_DNS_ACCESSLISTS | FEATURES_DNS_ACCESS_LISTS |
| FEATURES_DNS_SERVERCONFIG | FEATURES_DNS_SERVER_CONFIG |
| FEATURES_GENERALSETTINGS | FEATURES_GENERAL_SETTINGS |
| FEATURES_QUERYLOGCONFIG | FEATURES_QUERY_LOG_CONFIG |
| FEATURES_STATSCONFIG | FEATURES_STATS_CONFIG |
| FEATURES_CLIENTSETTINGS | FEATURES_CLIENT_SETTINGS |
| ORIGIN_WEBURL | ORIGIN_WEB_URL |
| ORIGIN_APIPATH | ORIGIN_API_PATH |
| ORIGIN_INSECURE_SKIP_VERIFY | ORIGIN_INSECURE_SKIP_VERIFY |
| *REPLICA_WEBURL | REPLICA_WEB_URL |
| *REPLICA_APIPATH | REPLICA_API_PATH |
| *REPLICA_INSECURE_SKIP_VERIFY | REPLICA_INSECURE_SKIP_VERIFY |
| *REPLICA_AUTOSETUP | REPLICA_AUTO_SETUP |
| *REPLICA_INTERFACENAME | REPLICA_INTERFACE_NAME |

\* is also valid for numbered `REPLICA#_` variables

## Current sync features

- General Settings
- Filters
- Rewrites
- Services
- Clients
- DNS Config
- DHCP Config

By default, all features are enabled. Single features can be disabled in the config.

### Setup of initial instances

New AdGuardHome replica instances can be automatically installed if enabled via the config autoSetup. During automatic
installation, the admin interface will be listening on port 3000 in runtime.

To skip automatic setup

## Install

Get from [releases](https://github.com/bakito/adguardhome-sync/releases) or install from source

```bash
go install github.com/bakito/adguardhome-sync@latest
```

## Prerequisites

Both the origin instance must be initially setup via the AdguardHome installation wizard.

## Username / Password vs. Cookie

Some instances of AdGuard Home do not support basic authentication. For instance, many routers with built-in Adguard
Home support do not. If this is the case, a valid cookie may be provided instead. If the router protects the AdGuard
instance behind its own authentication, the cookie from an authenticated request may allow the sync to succeed.

- This has been tested successfully against GL.Inet routers with AdGuard Home.
- Note: due to the short validity of cookies, this approach is likely only suitable for one-time syncs

## Run Linux/Mac

```bash

export LOG_LEVEL=info
export ORIGIN_URL=https://192.168.1.2:3000
export ORIGIN_USERNAME=username
export ORIGIN_PASSWORD=password
# export ORIGIN_COOKIE=Origin-Cookie-Name=CCCOOOKKKIIIEEE
export REPLICA_URL=http://192.168.1.3
export REPLICA_USERNAME=username
export REPLICA_PASSWORD=password
# export REPLICA_COOKIE=Replica-Cookie-Name=CCCOOOKKKIIIEEE

# run once
adguardhome-sync run

# run as daemon
adguardhome-sync run --cron "*/10 * * * *"
```

## Run Windows

```bash
@ECHO OFF
@TITLE AdGuardHome-Sync

REM set LOG_LEVEL=debug
set LOG_LEVEL=info
REM set LOG_LEVEL=warn
REM set LOG_LEVEL=error

set ORIGIN_URL=http://192.168.1.2:3000
set ORIGIN_USERNAME=username
set ORIGIN_PASSWORD=password
# set ORIGIN_COOKIE=Origin-Cookie-Name=CCCOOOKKKIIIEEE

set REPLICA_URL=http://192.168.2.2:3000
set REPLICA_USERNAME=username
set REPLICA_PASSWORD=password
# set REPLICA_COOKIE=Replica-Cookie-Name=CCCOOOKKKIIIEEE

set FEATURES_DHCP=false
set FEATURES_DHCP_SERVERCONFIG=false
set FEATURES_DHCP_STATICLEASES=false

# run once
adguardhome-sync run

# run as daemon
adguardhome-sync run --cron "*/10 * * * *"
```

## docker cli

```bash
docker run -d \
  --name=adguardhome-sync \
  -p 8080:8080 \
  -v /path/to/appdata/config/adguardhome-sync.yaml:/config/adguardhome-sync.yaml \
  --restart unless-stopped \
  ghcr.io/bakito/adguardhome-sync:latest
```

## docker compose

### config file

```yaml
---
version: "2.1"
services:
  adguardhome-sync:
    image: ghcr.io/bakito/adguardhome-sync
    container_name: adguardhome-sync
    command: run --config /config/adguardhome-sync.yaml
    volumes:
      - /path/to/appdata/config/adguardhome-sync.yaml:/config/adguardhome-sync.yaml
    ports:
      - 8080:8080
    restart: unless-stopped
```

### env

```yaml
---
version: "2.1"
services:
  adguardhome-sync:
    image: ghcr.io/bakito/adguardhome-sync
    container_name: adguardhome-sync
    command: run
    environment:
      LOG_LEVEL: "info"
      ORIGIN_URL: "https://192.168.1.2:3000"
      # ORIGIN_WEB_URL: "https://some-other.url" # used in the web interface (default: <origin-url>

      ORIGIN_USERNAME: "username"
      ORIGIN_PASSWORD: "password"
      REPLICA_URL: "http://192.168.1.3"
      REPLICA_USERNAME: "username"
      REPLICA_PASSWORD: "password"
      REPLICA1_URL: "http://192.168.1.4"
      REPLICA1_USERNAME: "username"
      REPLICA1_PASSWORD: "password"
      REPLICA1_API_PATH: "/some/path/control"
      # REPLICA1_WEB_URL: "https://some-other.url" # used in the web interface (default: <replica-url>
      # REPLICA1_AUTO_SETUP: true # if true, AdGuardHome is automatically initialized.
      # REPLICA1_INTERFACE_NAME: 'ens18' # use custom dhcp interface name
      # REPLICA1_DHCP_SERVER_ENABLED: true/false (optional) enables/disables the dhcp server on the replica
      CRON: "*/10 * * * *" # run every 10 minutes
      RUNONSTART: true
      # CONTINUE_ON_ERROR: false # If enabled, the synchronisation task will not fail on single errors, but will log the errors and continue

      # Configure the sync API server, disabled if api port is 0
      API_PORT: 8080

      # Configure sync features; by default all features are enabled.
      # FEATURES_GENERAL_SETTINGS: true
      # FEATURES_QUERY_LOG_CONFIG: true
      # FEATURES_STATS_CONFIG: true
      # FEATURES_CLIENT_SETTINGS: true
      # FEATURES_SERVICES: true
      # FEATURES_FILTERS: true
      # FEATURES_DHCP_SERVER_CONFIG: true
      # FEATURES_DHCP_STATIC_LEASES: true
      # FEATURES_DNS_SERVER_CONFIG: true
      # FEATURES_DNS_ACCESS_LISTS: true
      # FEATURES_DNS_REWRITES: true
    ports:
      - 8080:8080
    restart: unless-stopped
```

### Config file

location: $HOME/.adguardhome-sync.yaml

```yaml
# cron expression to run in daemon mode. (default; "" = runs only once)
cron: "*/10 * * * *"

# runs the synchronisation on startup
runOnStart: true

# If enabled, the synchronisation task will not fail on single errors, but will log the errors and continue
continueOnError: false

origin:
  # url of the origin instance
  url: https://192.168.1.2:3000
  # apiPath: define an api path if other than "/control"
  # insecureSkipVerify: true # disable tls check
  username: username
  password: password
  # cookie: Origin-Cookie-Name=CCCOOOKKKIIIEEE

# replicas instances
replicas:
  # url of the replica instance
  - url: http://192.168.1.3
    username: username
    password: password
    # cookie: Replica1-Cookie-Name=CCCOOOKKKIIIEEE
  - url: http://192.168.1.4
    username: username
    password: password
    # cookie: Replica2-Cookie-Name=CCCOOOKKKIIIEEE
    # autoSetup: true # if true, AdGuardHome is automatically initialized.
    # webURL: "https://some-other.url" # used in the web interface (default: <replica-url>

# Configure the sync API server, disabled if api port is 0
api:
  # Port, default 8080
  port: 8080
  # if username and password are defined, basic auth is applied to the sync API
  username: username
  password: password
  # enable api dark mode
  darkMode: true

# Configure sync features; by default all features are enabled.
features:
  generalSettings: true
  queryLogConfig: true
  statsConfig: true
  clientSettings: true
  services: true
  filters: true
  dhcp:
    serverConfig: true
    staticLeases: true
  dns:
    serverConfig: true
    accessLists: true
    rewrites: true
```

## Log Level

The log level can be set with the environment variable: LOG_LEVEL

The following log levels are supported (default: info)

- debug
- info
- warn
- error