futamidev/blok

By futamidev

•Updated 8 days ago

Control your access internet

Image

Networking

Security

Monitoring & observability

2.1K

Overview Tags

futamidev/blok repository overview

⁠🛡️ blok v0.1.16 - Digital Wellbeing Network DNS Proxy

blok is a high-performance, lightweight network-level Digital Wellbeing DNS Proxy and Web Dashboard designed to enforce focus rules, parental controls, and distraction-free networking across all devices in your home or office network.

Acting as an intelligent middleman between client devices and DNS upstreams, blok evaluates DNS queries against time windows, usage quotas, package rules, and priority latencies with zero hardcoded product names and a Mobile-First responsive interface.

⁠🌟 Key Features in v0.1.16

⏳ Digital Wellbeing Time & Quota Controls: Enforce strict focus schedules (time_start, time_end), active usage quotas (use_time: 1h), break intervals (break_time: 30m), and repeat counts (use_many). Supports custom landing page redirects (redirect: /login/).
⚡ Passthrough Priority Chain: Labeled & Default Priority groups evaluate before standard rules and pass through immediately (DecisionAllow, IsPriority: true) with configured bandwidth speeds (priority_speed: 3.2M or custom chunk_speed).
🔒 Encrypted DNS Server (DoH & DoT): Built-in support for RFC 8484 DNS-over-HTTPS (DoH) (8443) and DNS-over-TLS (DoT) (853) with automatic self-signed TLS certificate generation.
🌐 Content-Aware Block Page: Direct browser navigation (Accept: text/html) redirects users to a customizable Glassmorphism landing page (/block), while background ad slots, tracking pixels, and XHR requests return HTTP 204 No Content to prevent broken app layouts.
⚡ Low-Resource & MicroSD Protection: Configurable memory tuning (use_low_memory: 0.45 or true) for 512MB–1GB RAM SBCs (Armbian, STB Amlogic, Pi Zero) and asynchronous non-blocking log flusher (optimize_sd_card: true) to prevent MicroSD wear-and-tear.
🔄 Zero-Downtime Hot Reload & Filter Download: Automatically reloads modifications in main.yml, package/*.txt, rule/*.yml, and web/* on-the-fly, downloading external blocklists and rebuilding lookup tables without restarting the binary.

⁠🗂️ Configuration Structure (`config/`)

config/
├── main.yml             # Global DNS, Web, DoH/DoT, Upstream & Optimization settings
├── web/
│   ├── index.html       # Custom block landing page HTML template
│   └── style.css        # Custom block page styling
├── package/
│   ├── streaming.txt    # Streaming package domains & priorities
│   ├── gaming.txt       # Gaming domains & port priorities
│   └── adblock.txt      # External blocklists & ad domains
├── rule/
│   └── default.yml      # Time-window rules and device IP assignments
└── logs/                # Dynamic query log storage

⁠📖 Complete Configuration & Usage Tutorial

⁠1. Main Configuration (`config/main.yml`)

main.yml defines DNS server ports, upstream DNS resolvers, global priority rules, and memory tuning:

dns_port: 53                # DNS UDP/TCP listening port
web_port: 6767              # Web Dashboard listening port
dns_over_https: 8443        # Enable DoH (true = 8443 or explicit port)
dns_over_tls: 853           # Enable DoT (true = 853 or explicit port)
max_speed: 16M              # Optional max ISP speed
priority_speed: 3.2M        # Default priority bandwidth speed (3.2M, 10M, 50M, 0.7G)

timezone: Asia/Jakarta      # Application timezone
reset_time: "00.00"         # Daily quota reset time (HH.MM)

use_security_web: true      # Google Safe Browsing v5 integration
use_low_memory: 0.45        # RAM optimization (bool or float GC threshold)
optimize_sd_card: true      # MicroSD protection (async batch log flusher)
log_age: 30d                # Log retention duration
refresh_package: 1w         # Auto refresh external blocklists (1m, 1w, 1d)

upstreams:                  # Upstream DNS resolvers
  - 1.1.1.1:53
  - 94.140.14.14:53

rewrite:                    # Local DNS IP rewrites
  - "?myrouter.local"                 # Resolves to local server IP automatically
  - "?custom.dev->192.168.1.50"       # Resolves custom.dev to specific IP
  - "!=npm.myrouter.local"            # Excludes domain from rewrite (bypasses to upstream)

priority:                   # Global default priority list
  - /package/streaming
  - "tcp: 443"
  - "udp: 7000-7050, 27015-27030"

⁠2. Rule Files (`config/rule/*.yml`)

Rule files control schedule windows, usage quotas, target client IPs, blocklists, and priority shorthands:

time_start: 06.30           # Start time for web access (HH.MM)
time_end: 21.30             # End time for web access (HH.MM)
use_time: 1h                # Active usage quota duration
break_time: 30m             # Required break interval after quota expires
use_many: 0                 # Quota repetition count (0 = infinite)
redirect: /login/           # Custom landing page redirect URL

ip:                         # Target device IP addresses ("*" for all client IPs)
  - "*"

rule:                       # Blocked packages, domains, or wildcard rules
  - /package/adblock
  - /package/streaming
  - *                       # Block all web access except whitelist & LAN IPs
  - 192.168.0.99:30         # Target IP:Port block rule

whitelist:                  # Domain allowlist & priority shorthands (overrides rules)
  - duckduckgo.com
  - *priority               # Whitelist any local priority in this rule
  - **p                     # Whitelist any global priority in main.yml (**priority)
  - *p: "Traffic Game"      # Whitelist labeled priority group matching "Traffic Game"

priority:                   # Rule-specific priority items
  - /package/gaming
  - "udp: 7000-7050"

⁠3. Package Files (`config/package/*.txt`)

Package files contain domain blocklists, allowlists, custom priority labels, or external blocklist URLs:

# Custom Labeled Priority Group (evaluated first with custom speed)
use_priority_label: "Traffic Game HighSpeed"
chunk_speed: 50M

# Domain & Port Definitions
example-game.com
!allowed-cdn.com            # Whitelist domain inline
*wildcard-game.com          # Wildcard match
||ad-server.com^           # AdBlock Plus syntax
127.0.0.1 tracking.com      # Hosts file format

# External Blocklists / Allowlists
use_blocklist: https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
use_whitelist: https://example.com/allowlist.txt

# Priority Definitions
use_priority: game-cdn.com
tcp: 443, 21027
udp: 7000-7050, 27015-27030

⁠🐳 Running via Docker

⁠Option 1: Docker Compose (Recommended)

version: '3.8'

services:
  blok:
    image: futamiyarn/blok:latest
    container_name: blok
    restart: unless-stopped
    network_mode: "host" # Recommended for DNS binding
    volumes:
      - ./config:/app/config
    tmpfs:
      - /app/config/logs:size=16M # Store logs in RAM tmpfs to protect MicroSD card
    environment:
      - TZ=Asia/Jakarta
      - GOGC=50
    cap_add:
      - NET_BIND_SERVICE
    mem_limit: 64m

Start the container:

docker-compose up -d

⁠Option 2: Docker CLI

docker run -d \
  --name blok \
  --net=host \
  -v $(pwd)/config:/app/config \
  --memory=64m \
  --restart=unless-stopped \
  futamiyarn/blok:latest

⁠💻 Running Standalone Binary

Pre-compiled release binaries are located in bin/:

bin/blok_linux_amd64: Linux x86_64 / PC / Proxmox Server
bin/blok_linux_arm64: ARMv8 64-bit (Raspberry Pi 4/5, Armbian 64-bit, STB Amlogic)
bin/blok_linux_armv7: ARMv7 32-bit (STB HG680P, Raspberry Pi 32-bit)

# Make binary executable
chmod +x bin/blok_linux_amd64

# Run with custom config directory
./bin/blok_linux_amd64 -config /etc/blok/config

⁠🛠️ Building from Source

Prerequisites: Go 1.22+

# Clone the repository
git clone https://github.com/futamiyarn/blok.git
cd blok

# Run unit tests
go test ./...

# Build all release binaries
chmod +x build.sh
./build.sh

⁠🌐 Web Dashboard & API

Access the Mobile-First Web Dashboard in your browser: http://localhost:6767 or http://<YOUR_SERVER_IP>:6767

Tag summary

Recent tags

Content type

Image

Digest

sha256:143d1f164…

Size

10.5 MB

Last updated

8 days ago

docker pull futamidev/blok

Help

System theme

Docker Suite