---

📋 목차

• 빠른 시작
• 개요
• 작동 방식
• 사전 요구 사항
• 상세 설치 가이드
• 설정
• 사용 및 확인
• 문제 해결
• 제거
• 라이선스

---

🚀 빠른 시작

1단계: API 토큰 받기

tip.qfeeds.com에서 무료 API 키를 받으세요.

2단계: 스크립트 다운로드```bash

git clone https://github.com/Q-Feeds/NFtables-IPtables-integration-script.git cd NFtables-IPtables-integration-script chmod +x qfeeds-installer.sh qfeeds-uninstaller.sh

### 단계 3: 설치 프로그램을 root로 실행하십시오```bash
sudo ./qfeeds-installer.sh

설치 프로그램이 수행하는 작업:

1. 방화벽 백엔드를 자동 감지합니다(nftables 또는 iptables)
2. API 토큰, 차단 옵션 및 선택적 화이트리스트를 입력하도록 안내합니다
3. 모든 종속성, 업데이터 스크립트 및 크론 작업을 설치합니다
4. 즉시 첫 번째 전체 동기화를 수행합니다

4단계: 완료

이제 서버가 보호됩니다. 크론 작업은 20분마다(구성 가능) 업데이트를 확인하며, 실제 API 호출은 라이선스가 허용할 때만 발생합니다.

---

📖 개요

이 솔루션은 Q-Feeds의 최신 위협 인텔리전스 피드를 주기적으로 다운로드하여 방화벽 규칙으로 적용함으로써 다음을 가능하게 합니다:

• ✅ 알려진 악성 IP의 인바운드 연결 차단
• ✅ 알려진 악성 IP의 아웃바운드 연결 차단
• ✅ 자체 IP/CIDR 화이트리스트 등록으로 잠금 현상 방지
• ✅ Q-Feeds 라이선스 기반 자동 스케줄링
• ✅ 차분(diff) 기반 동기화를 통한 증분 업데이트로 리소스 사용 최소화

이러한 접근 방식의 이유

• ✅ 백엔드 자동 감지 — 수동 선택 없이 nftables 또는 iptables+ipset에서 작동
• ✅ 빠름 — 최적화된 해시 집합(nftables) 또는 ipset(iptables)을 사용하여 40만 개 이상의 IP를 초 단위로 로드
• ✅ 안전함 — 전용 테이블/집합 사용 — 기존 방화벽 규칙을 전혀 건드리지 않음
• ✅ 효율적 — 차분 기반 업데이트로 전체 목록이 아닌 변경 사항만 처리
• ✅ 신뢰성 — 자가 복구: 빈 로컬 집합 또는 불완전한 로컬 집합(예: 재부팅 후)을 감지하여 재구축하고, diff 실패 시 자동으로 전체 동기화로 대체
• ✅ 유연함 — 인바운드/아웃바운드 차단 선택 가능, 선택적 화이트리스트

---

🔧 작동 방식

백엔드 감지

설치 프로그램이 사용 가능한 방화벽 백엔드를 자동으로 감지합니다:

우선순위	감지 조건	백엔드
1순위	nft 명령어 발견	nftables
2순위	iptables 명령어 발견	iptables+ipset
—	둘 다 없음	오류(종료)

감지된 백엔드는 구성 파일에 저장됩니다. 업데이터 및 제거 스크립트는 이를 사용하여 올바른 방화벽 명령어를 실행합니다.

아키텍처: 두 가지 집합 유형

두 백엔드 모두 최대 성능을 위해 동일한 분할 집합 전략을 사용합니다:

nftables 백엔드:``` ┌─────────────────────────────────────────────────────────┐ │ table ip qfeeds │ │ │ │ ┌─────────────────────────┐ ┌───────────────────────┐ │ │ │ qfeeds_blacklist_v4 │ │ qfeeds_blacklist_v4 │ │ │ │ (hash set) │ │ _nets (interval set) │ │ │ │ │ │ │ │ │ │ Individual IPs │ │ CIDR ranges │ │ │ │ ~99% of entries │ │ ~1% of entries │ │ │ │ O(1) lookup & insert │ │ O(log n) lookup │ │ │ └─────────────────────────┘ └───────────────────────┘ │ │ │ │ ┌─────────────────────────┐ │ │ │ qfeeds_whitelist_v4 │ │ │ │ (interval set) │ │ │ │ Your allowed IPs/CIDRs │ │ │ └─────────────────────────┘ │ │ │ │ chain input-chain (hook input, priority 0, accept) │ │ → ip saddr @qfeeds_whitelist_v4 accept │ │ → ip saddr @qfeeds_blacklist_v4 drop │ │ → ip saddr @qfeeds_blacklist_v4_nets drop │ │ │ │ chain output-chain (if enabled) │ │ → ip daddr @qfeeds_whitelist_v4 accept │ │ → ip daddr @qfeeds_blacklist_v4 drop │ │ → ip daddr @qfeeds_blacklist_v4_nets drop │ └─────────────────────────────────────────────────────────┘

**iptables+ipset 백엔드:**```
┌──────────────────────────────────────────────────────────┐
│  ipset sets                                              │
│                                                          │
│  ┌─────────────────────────┐  ┌────────────────────────┐ │
│  │ qfeeds_blacklist_v4     │  │ qfeeds_blacklist_v4    │ │
│  │ (hash:ip)               │  │ _nets (hash:net)       │ │
│  │ maxelem 1000000         │  │ maxelem 65536          │ │
│  │                         │  │                        │ │
│  │ Individual IPs          │  │ CIDR ranges            │ │
│  └─────────────────────────┘  └────────────────────────┘ │
│                                                          │
│  ┌─────────────────────────┐                             │
│  │ qfeeds_whitelist_v4     │                             │
│  │ (hash:net)              │                             │
│  └─────────────────────────┘                             │
│                                                          │
│  iptables: INPUT/OUTPUT jump to a dedicated chain        │
│  (jump rule tagged -m comment "qfeeds"):                 │
│                                                          │
│  chain QFEEDS_INPUT (rebuilt each run, in order):        │
│    -m set --match-set whitelist_v4 src -j ACCEPT         │
│    -m set --match-set blacklist_v4 src -j DROP           │
│    -m set --match-set blacklist_v4_nets src -j DROP      │
│    (QFEEDS_OUTPUT mirrors this with dst, if enabled)     │
└──────────────────────────────────────────────────────────┘

동일한 구조가 IPv6(ip6 qfeeds 테이블 또는 ip6tables + family inet6 ipsets)에도 존재합니다.

두 가지 세트 유형을 사용하는 이유는?

• 해시 세트는 O(1) 삽입 및 조회로 개별 IP를 저장합니다 — 400k+ 개의 IP를 로드하는 데 몇 초가 걸립니다.
• 넷/인터벌 세트는 피드에 있는 소수의 CIDR 범위에만 사용됩니다.
• 이렇게 하면 수십만 개의 항목이 있는 단일 세트를 느리게 만드는 비용이 많이 드는 병합 작업을 피할 수 있습니다.

업데이트 흐름```

┌──────────────────────────────────────────────────────┐ │ 1. Check license schedule (licenses.php API) │ │ → Skip run if not yet time for next update │ │ 2. Determine sync mode (full or diff) │ │ 3. Fetch IPv4 feed (ipv6=0) and IPv6 feed │ │ (ipv6=only) separately │ │ 4. Separate IPs from CIDRs in awk │ │ 5. Batch-load into hash set (IPs) and net/interval │ │ set (CIDRs) │ │ 6. Update whitelist sets from config │ │ 7. Persist rules │ └──────────────────────────────────────────────────────┘

### Full Sync vs Diff Sync

| Mode | When | What it does |
|------|------|-------------|
| **Full sync** | First run, forced update, after a diff failure, when the local set has lost its baseline (empty or much smaller than expected), or when the last sync is older than `FULL_SYNC_MAX_AGE` (default 24h) | Fetches and validates each feed first, then flushes and reloads the blacklist sets. The set is only flushed once valid data is in hand, so a failed fetch never leaves you unprotected |
| **Diff sync** | Subsequent runs (`malware_ip` feed only) with a healthy local set | Fetches only additions (`+`) and removals (`-`) since last pull |

The diff sync is **per API key** — the API tracks your last successful pull and only returns changes since then. If a diff fails, the script automatically falls back to a full sync.

> **Self-healing:** Diff updates only patch the existing set. If that set is ever lost or truncated — for example a reboot where the firewall rules were not persisted, a manual flush, or a previous partial sync — the updater detects the missing baseline (live element count is 0 or far below the last recorded count) and forces a full rebuild instead of diffing onto an empty set. As an extra safety net it also forces a periodic full sync (every 24h by default, via `FULL_SYNC_MAX_AGE`).

### License-Based Scheduling