Metadata-Version: 2.4
Name: adguardhome-logsync
Version: 0.1.0
Summary: A Python tool to synchronize AdGuard Home query logs between multiple instances
Author-email: xz-dev <xiangzhedev@gmail.com>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/xz-dev/AdGuardHomeLogSync
Project-URL: Repository, https://github.com/xz-dev/AdGuardHomeLogSync
Project-URL: Issues, https://github.com/xz-dev/AdGuardHomeLogSync/issues
Keywords: adguard,dns,log,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sortedcontainers==2.4.0
Requires-Dist: orjson==3.10.18
Requires-Dist: aiofiles==24.1.0
Dynamic: license-file

# AdGuard Home Log Sync

A Python tool to synchronize AdGuard Home query logs between multiple instances.

## Description

AdGuard Home Log Sync allows you to merge and synchronize query logs from multiple AdGuard Home instances. This is useful when you're running multiple AdGuard Home instances and want to maintain a unified query log.

## Features

- Backup existing query logs
- Merge multiple query log files
- Safe atomic replacement of original logs
- Command-line interface for easy automation

## Installation

### Using pipx (Recommended)

Install from PyPI:
```bash
pipx install adguardhome-logsync
```

Install from Git repository:
```bash
pipx install git+https://github.com/xz-dev/AdGuardHomeLogSync.git
```

### Using pip

Install from PyPI:
```bash
pip install adguardhome-logsync
```

Install from Git repository:
```bash
pip install git+https://github.com/xz-dev/AdGuardHomeLogSync.git
```

## Usage

```bash
adguardhome-logsync --name <instance-name> --path <querylog-path> --backup <backup-directory>
```

### Parameters

- `--name`: Current instance nickname (required)
- `--path`: Path to the query log file (required)  
- `--backup`: Path to backup directory (required)

### Example

```bash
adguardhome-logsync --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup
```

### Example Output

```
Starting log synchronization for instance: genx
Backing up querylog...
Searching for querylog files...
Found 3 querylog files
Merging querylogs...
Writing merged querylog...
Moving to updated querylog at /tmp/tmp2eqv7rdc.json...
Log synchronization completed successfully
```

## Development

### Prerequisites

- Python 3.8+
- [uv](https://github.com/astral-sh/uv) (for development)

### Running from Source

Clone the repository:
```bash
git clone https://github.com/xz-dev/AdGuardHomeLogSync.git
cd AdGuardHomeLogSync
```

Run with uv:
```bash
uv run main.py --name genx --path ~/adg/workdir/data/querylog.json --backup ~/adg/workdir/data/backup
```

### Project Structure

```
AdGuardHomeLogSync/
├── main.py                 # Main entry point
├── utils/
│   ├── querylog_copy.py   # Backup and file operations
│   └── querylog_merge.py  # Log merging logic
├── pyproject.toml         # Project configuration
└── README.md             # This file
```

## How It Works

1. **Backup**: Creates a backup of the current query log with instance name
2. **Discovery**: Searches for all query log files in the backup directory
3. **Merge**: Combines all found query logs into a single unified log
4. **Replace**: Safely replaces the original query log with the merged version

## Requirements

- AdGuard Home instances with JSON format query logs
- Write access to query log files and backup directory
- Python 3.8 or higher

## License

BSD-3-Clause

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Issues

Please report issues at: https://github.com/xz-dev/AdGuardHomeLogSync/issues
