پرش به مطلب اصلی

نصب

WaterWall به‌صورت یک فایل اجرایی مستقل منتشر می‌شود و به سرویس package manager، database یا runtime جداگانه‌ای نیاز ندارد. کافی است نسخه‌ی مناسب سیستم‌عامل خود را دانلود کنید، فایل core.json را کنار فایل اجرایی بگذارید و برنامه را از همان دایرکتوری اجرا کنید.

بیشتر کاربران WaterWall را روی یک VPS لینوکسی اجرا می‌کنند. می‌توانید از Windows با SSH یا VS Code Remote SSH فایل‌ها را مدیریت کنید، اما دستورهای زیر را باید روی خود سرور اجرا کنید.

دانلود​

آخرین نسخه را از صفحه‌ی release‌های WaterWall دانلود کنید. فایلی را انتخاب کنید که با سیستم‌عامل و معماری CPU شما سازگار باشد.

build‌های Linux x64، از جمله نسخه‌های old-CPU و AVX512، با همان نام‌های قبلی به‌صورت فایل اجرایی فشرده منتشر می‌شوند. فایل را مثل همیشه اجرا کنید؛ برنامه هنگام شروع در حافظه از حالت فشرده خارج می‌شود و فایل اجرایی موقتی روی دیسک نمی‌سازد. این build‌ها به Linux 3.19 یا جدیدتر، memfd_create، قابلیت file sealing، execveat، مجوز اجرای فایل‌های ناشناسِ مبتنی بر حافظه و دسترسی خواندن به /proc/self/exe نیاز دارند. نیازمندی‌های CPU و کتابخانه‌های سیستمیِ build انتخاب‌شده همچنان برقرار است. راه‌اندازی با Set-ID یا file capabilities در loader فشرده پشتیبانی نمی‌شود.

دانلودهای Windows همچنان فایل اجرایی معمولی هستند. در build اختیاری از سورس با WW_PACK_RUNTIME=ON، برنامه در یک مسیر موقت خصوصی استخراج می‌شود و در process جدا اجرا می‌شود؛ launcher منتظر پایان آن می‌ماند و فایل موقت را پاک می‌کند. پیش از استفاده در release، این حالت باید روی Windows واقعی تست و تأیید شود. DLL‌های همراه باید کنار launcher بمانند. قوانین firewall و سرویس‌هایی که مسیر یا PID ثابت می‌خواهند باید process موقت را در نظر بگیرند؛ قانون مربوط به مسیر launcher برای آن کافی نیست. پایان اجباری ممکن است فایل موقت باقی بگذارد. فشرده‌سازی Windows ARM پشتیبانی نمی‌شود.

یک نصب دستی معمول در Linux به این شکل است:

mkdir -p ~/waterwall
cd ~/waterwall

# Put the downloaded archive or binary here, then extract it if needed.
chmod +x ./WaterWall

اگر فایل release فشرده است، ابتدا آن را با ابزار متناسب، مانند tar، unzip یا 7z، از حالت فشرده خارج کنید.

ساختار دایرکتوری​

یک راه‌اندازی کوچک معمولاً چنین ساختاری دارد:

waterwall/
  WaterWall
  core.json
  configs/
    local-test.json
  logs/

WaterWall به‌طور پیش‌فرض فایل ./core.json را از working directory خود می‌خواند. مسیرهای داخل core.json، از جمله فایل‌های آرایه‌ی configs، بدون تغییر به loader داده می‌شوند؛ پس دقت کنید برنامه را از کدام دایرکتوری اجرا می‌کنید.

انتخاب فایل core یا خواندن از stdin​

می‌توانید از شکل‌های معادل -c:PATH، --c:PATH، -config:PATH، --config:PATH یا config:PATH استفاده کنید. مسیر می‌تواند نسبی یا مطلق باشد. برای ارسال مستقیم JSON از مقدار stdin استفاده کنید:

./WaterWall --config:/etc/waterwall/core.json
./WaterWall --config:stdin < core.json

به‌جای CLI می‌توانید متغیر محیطی WW_CORE_JSON_INPUT را روی یک مسیر یا stdin قرار دهید. گزینه‌ی CLI بر متغیر محیطی اولویت دارد و متغیر محیطی نیز بر مقدار پیش‌فرض ./core.json مقدم است.

انتخاب منبع جدید، working directory را تغییر نمی‌دهد. مسیرهای نسبی داخل JSON همچنان نسبت به دایرکتوری اجرای WaterWall محاسبه می‌شوند.

یک core.json حداقلی​

فایل core.json را کنار فایل اجرایی بسازید:

{
  "log": {
    "path": "logs/",
    "core": {
      "loglevel": "INFO",
      "file": "core.log",
      "console": true
    },
    "network": {
      "loglevel": "INFO",
      "file": "network.log",
      "console": true
    },
    "dns": {
      "loglevel": "INFO",
      "file": "dns.log",
      "console": true
    },
    "internal": {
      "loglevel": "INFO",
      "file": "internal.log",
      "console": true
    }
  },
  "misc": {
    "workers": 1,
    "ram-profile": "client",
    "mtu": 1500,
    "try-enabling-bbr": true,
    "libs-path": "libs/"
  },
  "dns": {
    "domain-strategy": "prefer-ipv4"
  },
  "configs": [
    "configs/local-test.json"
  ]
}

وجود آرایه‌ی configs الزامی است و این آرایه باید دست‌کم مسیر یک فایل config را داشته باشد. بخش‌های دیگر اختیاری‌اند، اما نوشتن صریح تنظیمات misc باعث می‌شود رفتار runtime روشن‌تر و قابل‌پیش‌بینی‌تر باشد.

یک chain ساده برای تست​

فایل configs/local-test.json را بسازید:

{
  "name": "local-test",
  "author": "waterwall-user",
  "config-version": 1,
  "core-minimum-version": 0,
  "nodes": [
    {
      "name": "listen-http",
      "type": "TcpListener",
      "settings": {
        "address": "127.0.0.1",
        "port": 8080
      },
      "next": "connect-example"
    },
    {
      "name": "connect-example",
      "type": "TcpConnector",
      "settings": {
        "address": "example.com",
        "port": 80
      }
    }
  ]
}

WaterWall را اجرا کنید:

cd ~/waterwall
./WaterWall

در ترمینالی دیگر، listener محلی را تست کنید:

curl -v http://127.0.0.1:8080/

اگر درخواست به example.com می‌رسد، فایل اجرایی، فایل core، config loader، TcpListener، DNS resolver و TcpConnector همگی درست کار می‌کنند.

اجرا روی VPS​

برای ارائه‌ی یک سرویس عمومی، listener‌ها را روی یک آدرس عمومی یا wildcard قرار دهید:

"address": "0.0.0.0"

سپس پورت را در firewall سیستم‌عامل یا cloud firewall باز کنید. برای مثال، اگر روی پورت 443 گوش می‌دهید، هم firewall سیستم‌عامل و هم firewall شرکت ارائه‌دهنده باید اتصال ورودی TCP روی پورت 443 را مجاز بدانند.

استفاده از پورت‌های پایین‌تر از 1024 معمولاً به دسترسی root یا قابلیتی مانند CAP_NET_BIND_SERVICE نیاز دارد. node‌های packet-level مانند TunDevice نیز ممکن است به دسترسی بیشتری نیاز داشته باشند، زیرا interface شبکه می‌سازند یا از آن استفاده می‌کنند.

مشکلات رایج​

core.json پیدا نمی‌شود: WaterWall را از دایرکتوری حاوی core.json اجرا کنید، مسیر را با --config:PATH یا WW_CORE_JSON_INPUT مشخص کنید، یا working directory را در service manager خود مشخص کنید.

فایل config پیدا نمی‌شود: همه‌ی مسیرهای موجود در configs را بررسی کنید. مسیرهای نسبی معمولاً نسبت به working directory فعلی محاسبه می‌شوند.

خطای Permission denied: دستور chmod +x ./WaterWall را اجرا کنید. اگر پورت listener کمتر از 1024 است، برنامه را با دسترسی لازم اجرا کنید یا برای تست پورت بالاتری در نظر بگیرید.

پورت از قبل در حال استفاده است: در Linux با دستور ss -ltnp process‌ای را پیدا کنید که روی آن پورت TCP گوش می‌دهد.

client‌های راه دور نمی‌توانند متصل شوند: آدرس listener، log‌های WaterWall، firewall لینوکس و firewall شرکت ارائه‌دهنده را بررسی کنید. listener‌ای که روی 127.0.0.1 قرار دارد فقط اتصال‌های محلی را می‌پذیرد.

نام domain resolve نمی‌شود: بخش dns در core.json، به‌ویژه گزینه‌های servers و domain-strategy، را بررسی کنید و سپس log موجود در logs/dns.log را ببینید.