نام (NAME)

turnutils_natdiscovery - ابزار کشف رفتار نگاشت و فیلترینگ NAT طبق RFC 5780

اطلاعات عمومی (GENERAL INFORMATION)

مجموعه‌ای از برنامه‌های *turnutils_ عملکردهای سودمندی را برای آزمایش و راه‌اندازی سرور TURN ارائه می‌دهند.

1.: turnutils_uclient: چندین کلاینت UDP، TCP، TLS یا DTLS را شبیه‌سازی می‌کند. (این برنامه صرفاً برای اهداف آزمایشی ارائه شده است!) تصویر باینری کامپایل‌شده این برنامه در زیرشاخه bin/ قرار دارد.
2.: turnutils_peer: یک سرور اکو (echo) ساده بدون حالت (stateless) و منحصراً UDP، برای استفاده به عنوان سرور نهایی در الگوی بازپخش ("peer"). برای هر بسته ورودی UDP، به سادگی آن را بازتاب می‌دهد. (این برنامه صرفاً برای اهداف آزمایشی ارائه شده است!) هنگامی که کلاینت‌های آزمایشی به صورت کلاینت به کلاینت ارتباط برقرار می‌کنند (زمانی که برنامه "turnutils_uclient" با گزینه "-y" استفاده می‌شود)، نیازی به turnutils_peer نیست.

تصویر باینری کامپایل‌شده این برنامه در زیرشاخه bin/ قرار دارد.

3.: turnutils_stunclient: یک نمونه کلاینت ساده STUN. تصویر باینری کامپایل‌شده این برنامه در زیرشاخه bin/ قرار دارد.
4.: turnutils_rfc5769check: ابزاری که صحت پیاده‌سازی پروتکل STUN/TURN را بررسی می‌کند. این ابزار فقط برای فرآیند بررسی زمان کامپایل استفاده می‌شود و در مسیر نصب کپی نمی‌شود.

در زیرشاخه "examples/scripts"، نمونه‌هایی از خطوط فرمان برای اجرای این برنامه‌ها خواهید یافت. اسکریپت‌ها برای اجرا از زیرشاخه examples/ در نظر گرفته شده‌اند، به عنوان مثال:

$ cd examples

$ ./scripts/secure_relay.sh

5.: turnutils_natdiscovery: ابزاری که کشف رفتار NAT را بر اساس RFC 5780 ارائه می‌دهد. این ابزار رفتار واقعی نگاشت و فیلترینگ NAT و غیره را کشف می‌کند. توجه داشته باشید که در سمت سرور TURN، دو آدرس IP شنیداری متفاوت باید پیکربندی شده باشد تا بتواند به درستی کار کند!
6.: turnutils_oauth: ابزاری که تولید (رمزنگاری AEAD)، اعتبارسنجی و رمزگشایی access_token در OAuth را فراهم می‌کند. این ابزار تمام کلیدها، طول عمرها و هرگونه اطلاعات مرتبط لازم برای ایجاد و اعتبارسنجی یک access_token را به عنوان ورودی دریافت می‌کند. خروجی آن یک JSON با تمام پارامترهای OAuth PoP است که باید به کلاینت منتقل شوند. خروجی طبق RFC 7635 پیوست B، شکل ۸ تولید می‌شود.

برای جزئیات بیشتر و ساختار access_token، سند RFC 7635 را بخوانید و اسکریپت موجود در examples/scripts/oauth.sh را بررسی کنید.

=====================================

نام (NAME)

turnutils_uclient - این برنامه شبیه‌سازی کلاینت فقط برای اهداف آزمایشی ارائه شده است.

خلاصه دستور (SYNOPSIS)

$ turnutils_uclient [-tTSvsyhcxg] [گزینه‌ها] <TURN-Server-IP-address>

این ابزار برای شبیه‌سازی چندین کلاینت طراحی شده است. از رابط برنامه‌نویسی ورودی/خروجی ناهمگام در libevent برای مدیریت چندین کلاینت استفاده می‌کند. یک کلاینت به سرور رله متصل می‌شود، نشست را مذاکره می‌کند و چندین پیام (تعداد پیکربندی‌شده) را به سرور (رله) ارسال می‌نماید و انتظار همان تعداد پاسخ را دارد. طول پیام‌ها قابل تنظیم است. پیام یک جریان بایت اختیاری است. تعداد پیام‌های ارسالی نیز قابل تنظیم است.

فلگ‌ها:

-t: استفاده از TCP برای ارتباط میان کلاینت و سرور TURN (پیش‌فرض UDP است).
-b: استفاده از SCTP برای ارتباط میان کلاینت و سرور TURN (پیش‌فرض UDP است).
-T: استفاده از TCP برای انتقال رله (پیش‌فرض - UDP). به طور ضمنی گزینه‌های -t، -y، -c را فعال کرده و فلگ‌ها و گزینه‌های -s، -e، -r و -g را نادیده می‌گیرد. می‌تواند همراه با -b استفاده شود.

-P: حالت غیرفعال Passive TCP (RFC 6062 با پیر فعال). به طور ضمنی -T را فعال می‌کند.
-S: اتصال امن SSL: استفاده از SSL/TLS برای TCP، پروتکل DTLS برای UDP، و TLS/SCTP برای SCTP.
-U: اتصال امن رمزنگاری‌نشده (مجموعه eNULL): استفاده از SSL/TLS برای TCP، و DTLS برای UDP.
-v: حالت پرحرف (Verbose).
-s: استفاده از متد "Send" در TURN؛ به صورت پیش‌فرض از کانال‌های TURN استفاده می‌شود.
-y: استفاده از اتصالات کلاینت به کلاینت: جفت کانال‌های RTP/RTCP به یک جفت کانال RTP/RTCP دیگر.

با این گزینه از برنامه turnutils_peer استفاده نمی‌شود، زیرا نقاط پایانی رله تخصیص‌یافته با یکدیگر گفتگو می‌کنند.

-h: معلق ماندن نامحدود پس از ارسال آخرین بسته.
-c: عدم ایجاد اتصالات rtcp.
-x: درخواست آدرس رله IPv6 (طبق RFC 6156).
-X: درخواست صریح آدرس رله IPv4.
-g: تنظیم پارامتر DONT_FRAGMENT در درخواست‌های TURN.
-D: انجام اجباری فاصله‌گذاری کانال حتی برای UDP (مانند pjnath).
-N: انجام آزمایش‌های منفی (فقط برخی موارد محدود).
-R: انجام آزمایش‌های منفی پروتکل.
-O: حالت حمله منع سرویس (DOS attack mode).
-M: استفاده از قابلیت تحرک TURN ICE Mobility.
-I: عدم تنظیم مجوزها روی نقاط پایانی رله TURN (برای آزمایش عملکرد رله غیر استاندارد سرور).

-G: تولید درخواست‌های اضافی (ایجاد مجوزها، اتصال کانال).
-B: قطع اتصال تصادفی پس از ارسال چند بسته اولیه.
-Z: تخصیص دوگانه (SSODA). مستلزم گزینه -c است.
-J: استفاده از oAuth با کلیدهای آزمایشی پیش‌فرض kid='north'، 'union' یا 'oldempire'.
-Y: حالت تولید بار (Load-generator): سیل بسته‌ها داده‌ها را از طریق یک تخصیص واحد TURN تا حد ممکن سریع ارسال می‌کند،

حالت alloc تخصیص‌ها را با حداکثر سرعت ایجاد می‌کند، و حالت invalid بسته‌های نامعتبر کوچک را با بیشترین سرعت ممکن به شنونده TURN می‌فرستد. حالت‌های مولد بار مستلزم -c هستند و از -y پشتیبانی نمی‌کنند.

--no-even-port: هرگز ویژگی EVEN-PORT را به درخواست‌های ALLOCATE متصل نکن. مسیر پیش‌فرض clnet_allocate به صورت تصادفی 0 یا -1 را حتی تحت -c انتخاب می‌کند، که حالت --multiplex-peer در turnserver صریحاً آن را با خطای 400 رد می‌کند. از --no-even-port برای اجرای تمیز alloc-flood و هرگونه آزمایش دیگر در برابر --multiplex-peer استفاده کنید.

--listener-threads <N>: تعداد ریسمان‌های دریافت‌کننده (شنونده) در مولد بار (همچنین با -K N در دسترس است). مقدار پیش‌فرض خودکار: 0 برای -m < 4، و ارتقا به 1 هنگامی که -m >= 4 باشد. مقدار 0 رفتار سنتی مبتنی بر یک رویداد واحد را حفظ می‌کند. هر شنونده base اختصاصی libevent خود را دارد؛ نشست‌ها به صورت چرخشی (round-robin) توزیع می‌شوند. حداکثر ۴.

--sender-threads <N>: تعداد ریسمان‌های ارسال‌کننده (مبتنی بر تایمر) در مولد بار. مقدار پیش‌فرض خودکار: 0 برای -m < 4، و ارتقا به 2 زمانی که -m >= 4 باشد. مقدار 0 ارسال تک‌ریسمانی سنتی را حفظ می‌کند (timer_handler ریسمان اصلی تمام نشست‌ها را پیمایش می‌کند). هر ارسال‌کننده base اختصاصی libevent و بخشی از نشست‌ها را در اختیار دارد؛ ارسال‌های مربوط به هر تیک در یک فراخوانی UDP-GSO sendmsg (یا sendmmsg در صورت عدم دسترسی به GSO) تجمیع می‌شوند. حداکثر ۴.

گزینه‌ها با مقادیر الزامی:

-l: طول پیام (پیش‌فرض: ۱۰۰ بایت).
-i: فایل گواهی (فقط برای اتصالات امن، اختیاری).
-k: فایل کلید خصوصی (فقط برای اتصالات امن).
-E: فایل CA برای اعتبارسنجی گواهی سرور، در صورتی که گواهی سرور باید تأیید شود.

-p: پورت سرور TURN (پیش‌فرض‌ها: ۳۴۷۸ غیرامن، ۵۳۴۹ امن).
-n: تعداد پیام‌های ارسالی (پیش‌فرض: ۵). در حالت مولد بار، -n تعداد عملیات‌ها برای هر کلاینت است.

در صورتی که در آن حالت حذف شود، کلاینت تا زمان وقفه دستی به کار ادامه می‌دهد.

-d: دستگاه رابط محلی (اختیاری، فقط لینوکس).
-L: آدرس IP محلی (اختیاری).
-m: تعداد کلاینت‌ها (پیش‌فرض: ۱، ۲ یا ۴، بسته به گزینه‌ها).
-e: آدرس پیر (Peer).
-r: پورت پیر (پیش‌فرض: ۳۴۸۰).
-z: فاصله بسته‌ها به ازای هر نشست بر حسب میلی‌ثانیه (پیش‌فرض: ۲۰). در حالت‌های مولد بار packet و invalid مقدار پیش‌فرض ۰ میلی‌ثانیه است.

-u: نام کاربری STUN/TURN.
-w: رمز عبور کاربر STUN/TURN.
-W: راز رمز TURN REST API. رمز متنی ساده (مانند "north") که در صورت پویا بودن در ستون value جدول turn_secret در پایگاه‌داده، یا در صورت ایستا بودن مقدار static-auth-secret تنظیم‌شده در فایل پیکربندی ذخیره شده است.

-C: نماد (نویسه) جداکننده برچسب زمان/نام کاربری در TURN REST API. مقدار پیش‌فرض : است.

-F: مجموعه رمزنگاری (Cipher suite) برای TLS/DTLS. مقدار پیش‌فرض DEFAULT است.
-o: مقدار ویژگی ORIGIN در STUN.
-a: پهنای باند برای درخواست پهنای باند در ALLOCATE. مقدار پیش‌فرض صفر است.

نکات حالت مولد بار (load-generator):

حالت packet همچنان تخصیص و راه‌اندازی عادی TURN را انجام می‌دهد و سپس بلافاصله بدون ایجاد وقفه ارسال را آغاز می‌کند.
حالت alloc نیازی به -e ندارد؛ مکرراً تخصیص‌های جدید ایجاد کرده و دوباره آن‌ها را می‌بندد.
حالت alloc نیازی به -e ندارد؛ مکرراً تخصیص‌های جدید ایجاد می‌کند، از یک پورت محلی کلاینت یکتا برای هر کدام استفاده می‌نماید، هر یک را به یک ip:port ساختگی اختصاصی متصل کرده و دوباره آن‌ها را می‌بندد.
حالت invalid نیازی به -e ندارد؛ به‌طور پیش‌فرض از داده‌های ۱۶ بایتی استفاده می‌کند مگر اینکه -l مشخص شود.

نمونه‌ها را در دایرکتوری "examples/scripts" ببینید.

======================================

نام (NAME)

turnutils_peer - یک سرور پشتیبان اکو ساده و منحصراً UDP.

خلاصه دستور (SYNOPSIS)

$ turnutils_peer [-v] [گزینه‌ها]

توضیحات (DESCRIPTION)

این برنامه صرفاً برای اهداف آزمایشی، به عنوان پیر برای برنامه turnutils_uclient استفاده می‌شود.

گزینه‌ها با مقادیر الزامی:

-p: پورت UDP شنیداری (پیش‌فرض: ۳۴۸۰).
-d: دستگاه رابط شنیداری (اختیاری)
-L: آدرس شنیداری سرور turnutils_peer. چندین آدرس شنیداری IPv4 و IPv6 قابل استفاده است. اگر آدرس شنیداری تعریف نشود، روی تمامی آدرس‌های IPv4 و IPv6 گوش می‌دهد.
-v: حالت پرحرف

========================================

نام (NAME)

turnutils_stunclient - یک کلاینت پایه STUN.

خلاصه دستور (SYNOPSIS)

$ turnutils_stunclient [گزینه‌ها] <STUN-Server-IP-address>

توضیحات (DESCRIPTION)

یک درخواست "جدید" STUN بر اساس RFC 5389 (از طریق UDP) ارسال کرده و اطلاعات پاسخ را نشان می‌دهد.

گزینه‌ها با مقادیر الزامی:

-p: پورت سرور STUN (پیش‌فرض: ۳۴۷۸).
-L: آدرس محلی مورد استفاده (اختیاری).
-f: اجبار به پردازش طبق RFC 5780.
-c: ارسال پیوسته درخواست‌های STUN binding و گزارش تأخیر رفت‌وبرگشت تا زمان وقفه دستی.
-i: فاصله زمانی میان درخواست‌های پیوسته به میلی‌ثانیه (پیش‌فرض: ۱۰۰۰).
-t: زمان انقضای پاسخ به میلی‌ثانیه (پیش‌فرض: ۳۰۰۰).

برنامه turnutils_stunclient نتایج نخستین درخواست را بررسی می‌کند، و اگر دریابد که سرور STUN از RFC 5780 پشتیبانی می‌کند (پاسخ بایندینگ این موضوع را آشکار می‌کند)، آنگاه turnutils_stunclient چند درخواست دیگر با پارامترهای متفاوت ارسال می‌کند تا قابلیت‌های کشف NAT را نشان دهد.

حالت مداوم هر پاسخ یا پایان مهلت زمانی را گزارش می‌دهد و هنگام متوقف شدن با Ctrl-C، نرخ اتلاف بسته و کمترین/میانگین/بیشترین تأخیر رفت‌وبرگشت را چاپ می‌کند.

این ابزار از پروتکل STUN "قدیمی" و "کلاسیک" (RFC 3489) پشتیبانی نمی‌کند.

=====================================

نام (NAME)

turnutils_rfc5769check - ابزاری که صحت پیاده‌سازی پروتکل STUN را بررسی می‌کند.

خلاصه دستور (SYNOPSIS)

$ turnutils_rfc5769check

توضیحات (DESCRIPTION)

ابزار turnutils_rfc5769check صحت پیاده‌سازی پروتکل STUN را در برابر بردارهای آزمایشی از پیش تعریف‌شده در RFC 5769 می‌سنجد و نتایج آزمایش‌ها را روی صفحه چاپ می‌کند. این ابزار فقط برای فرآیند بررسی زمان کامپایل استفاده می‌شود و در مقصد نصب کپی نمی‌شود.

نحوه استفاده:

$ turnutils_rfc5769check

=====================================

نام (NAME)

turnutils_natdiscovery - ابزاری برای کشف رفتار نگاشت و فیلترینگ NAT طبق RFC 5780.

خلاصه دستور (SYNOPSIS)

$ turnutils_natdiscovery [گزینه‌ها] <STUN-Server-FQDN-or-IP-address>

توضیحات (DESCRIPTION)

ابزار turnutils_natdiscovery رفتار نگاشت و فیلترینگ NAT را بررسی می‌کند تا مشخص کند آیا NAT در حال حاضر از نگاشت مستقل از نقطه پایانی (Endpoint-Independent)، وابسته به آدرس (Address-Dependent)، یا وابسته به آدرس و پورت (Address and Port-Dependent) استفاده می‌کند و/یا مشخص کند آیا NAT فیلترینگ مستقل از نقطه پایانی، وابسته به آدرس، یا وابسته به آدرس و پورت را به کار می‌برد یا خیر.

برای کشف رفتار NAT از یکی از فلگ‌های -m، -f، -c یا -H استفاده کنید.

فلگ‌ها:

-m: کشف رفتار نگاشت NAT
-f: کشف رفتار فیلترینگ NAT
-t: کشف رفتار طول عمر نگاشت NAT نیازمند یک تایمر (-T) است

-c: کشف رفتار تداخل (collision) در NAT
-H: کشف رفتار هیرپینینگ (hairpinning) در NAT
-P: افزودن ۱۵۰۰ بایت فاصله‌گذاری (Padding) به فرآیند کشف رفتار قابل استفاده در تمام موارد به جز کشف طول عمر نگاشت NAT

گزینه‌ها با مقادیر الزامی:

-p: پورت سرور STUN (پیش‌فرض: ۳۴۷۸)
-L: آدرس محلی مورد استفاده (اختیاری)
-l: پورت محلی مورد استفاده (همراه با -L)
-A: آدرس محلی ثانویه (اختیاری) برای کشف تداخل الزامی است

-T: تایمر طول عمر نگاشت بر حسب ثانیه در کشف رفتار طول عمر نگاشت استفاده می‌شود

نحوه استفاده:

$ turnutils_natdiscovery -m -f stun.example.com

=====================================

نام (NAME)

turnutils_oauth - ابزاری کمکی برای تولید/رمزنگاری و اعتبارسنجی/رمزگشایی access_token در OAuth

خلاصه دستور (SYNOPSIS)

$ turnutils_oauth [گزینه‌ها]

توضیحات (DESCRIPTION)

ابزار turnutils_oauth در رمزنگاری و/یا رمزگشایی access_token با AEAD (رمزنگاری احرازشده با داده‌های مرتبط) کمک می‌کند. این ابزار به سرور احراز هویت (Auth Server) در ساخت access_token کمک می‌رساند و همچنین برای اهداف اشکال‌زدایی در اعتبارسنجی و رمزگشایی access_token مفید است. این ابزار تمام کلیدها، طول عمرها و هرگونه اطلاعات مرتبط لازم برای رمزنگاری یا رمزگشایی یک access_token را به عنوان ورودی دریافت می‌کند. خروجی یک فایل JSON با تمام پارامترهای OAuth PoP است که باید به کلاینت منتقل شوند. خروجی طبق RFC 7635 پیوست B، شکل ۸ تولید می‌شود. این ابزار می‌تواند به ایجاد یک سرویس Auth Server کمک کند، اما توجه داشته باشید که این ابزار "کلید نشست" / "mac_key" تولید نمی‌کند و طول عمر "کلید نشست" / "mac_key" یا "Auth key" را بررسی نمی‌نماید. برای جزئیات بیشتر و ساختار access_token، سند RFC 7635 را بخوانید و مثال موجود در examples/scripts/oauth.sh را ببینید.

از فلگ‌های -e و/یا -d برای رمزنگاری یا رمزگشایی access_token استفاده کنید.

فلگ‌ها:

-h, --help: راهنمای استفاده
-v, --verbose: حالت پرحرف
-e, --encrypt: رمزنگاری توکن
-d, --decrypt: رمزگشایی و اعتبارسنجی توکن

گزینه‌ها با مقادیر الزامی:

-i, --server-name: نام سرور (حداکثر ۲۵۵ نویسه)
-j, --auth-key-id: شناسه کلید احراز هویت (حداکثر ۳۲ نویسه)
-k, --auth-key: کلید احراز هویت با کدگذاری base64
-l: --auth-key-timestamp برچسب زمان کلید احراز هویت (ثانیه از مبدأ زمان epoch)
-m, --auth-key-lifetime: طول عمر کلید احراز هویت به ثانیه
-n, --auth-key-as-rs-alg: الگوریتم رمزنگاری میان سرور صدور مجوز (AS) و سرور منبع (RS)
-o, --token-nonce: مقدار نانس (nonce) کدگذاری‌شده با base64: به صورت base64(12 octet) = 16 char
-p, --token-mac-key: کلید MAC کدگذاری‌شده با base64: به صورت base64(32 octet) = 44 char
-q, --token-timestamp: برچسب زمان در قالب ۶۴ بیتی بدون علامت (قالب بومی یونیکس)، به این ترتیب که ۴۸ بیت برای ثانیه‌های سپری‌شده از مبدأ زمان epoch در UTC و ۱۶ بیت برای کسرهای ۱/۶۴۰۰۰ ثانیه است.