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

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

1.: turnutils_uclient: چندین کلاینت UDP، TCP، TLS یا DTLS را شبیه‌سازی می‌کند. (این برنامه صرفاً برای مقاصد آزمایشی ارائه شده است!) تصویر باینری کامپایل‌شدهٔ این برنامه در زیرشاخهٔ bin/ قرار دارد.
2.: turnutils_peer: یک کارساز بازتاب (echo) ساده، بدون وضعیت و فقط UDP، برای استفاده به‌عنوان کارساز نهایی در الگوی رله («همتا» یا peer). برای هر بستهٔ UDP ورودی، صرفاً آن را بازتاب می‌دهد. (این برنامه صرفاً برای مقاصد آزمایشی ارائه شده است!) هنگامی که کلاینت‌های آزمایشی به‌صورت کلاینت‌به‌کلاینت (client-to-client) ارتباط برقرار می‌کنند (زمانی که برنامهٔ «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 مطابق با RFC5780. این ابزار رفتار واقعی نگاشت (Mapping) و فیلترگذاری (Filtering) در NAT و غیره را کشف می‌کند. توجه داشته باشید که در سمت کارساز TURN، باید دو نشانی IP شنود متفاوت پیکربندی شده باشد تا بتواند به‌درستی کار کند!
6.: turnutils_oauth: ابزاری که تولید (رمزنگاری AEAD)، اعتبارسنجی و رمزگشایی access_token در OAuth را فراهم می‌کند. این ابزار تمامی کلیدها، زمان‌های حیات و هرگونه اطلاعات مرتبطِ مورد نیاز برای ایجاد و اعتبارسنجی یک access_token را دریافت می‌کند. خروجی آن یک JSON شامل تمام پارامترهای OAuth PoP است که باید به کلاینت منتقل شوند. خروجی بر اساس ضمیمهٔ B شکل ۸ در RFC7635 تولید می‌شود.

برای جزئیات بیشتر و ساختار access_token، سند rfc7635 را مطالعه کرده و اسکریپت موجود در examples/scripts/oauth.sh را ببینید.

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

نام (NAME)

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

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

$ turnutils_uclient [-tTSvsyhcxg] [options] <TURN-Server-IP-address>

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

پرچم‌ها:

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

با -b استفاده شود.

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

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

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

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

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

--no-even-port: هرگز صفت EVEN-PORT را به درخواست‌های ALLOCATE ضمیمه نکنید. مسیر پیش‌فرض clnet_allocate حتی تحت -c نیز به‌صورت تصادفی 0 یا -1 را انتخاب می‌کند،

که حالت --multiplex-peer در turnserver آن را اکیداً با خطای 400 رد می‌کند. از --no-even-port برای اجرای بی‌نقص alloc-flood و هرگونه آزمایش دیگر در برابر --multiplex-peer استفاده کنید.

--listener-threads <N>: تعداد ریسه‌های دریافت (شنونده) در loadgen (همچنین به‌صورت -K N در دسترس است). پیش‌فرض خودکار است: 0 برای -m < 4، و افزایش به 1

هنگامی که -m >= 4 باشد. مقدار 0 رفتار قدیمی single-event-base را حفظ می‌کند. هر شنونده libevent base مختص به خود را دارد؛ نشست‌ها به‌صورت round-robin تسهیم می‌شوند. حداکثر 4.

--sender-threads <N>: تعداد ریسه‌های ارسال (مبتنی بر زمان‌سنج) در loadgen. پیش‌فرض خودکار است: 0 برای -m < 4، و افزایش به 2 هنگامی که -m >= 4 باشد. مقدار 0

رفتار سنتی ارسال تک‌ریسه‌ای (که در آن timer_handler ریسه اصلی روی تمام نشست‌ها پیمایش می‌کند) را حفظ می‌کند. هر ارسال‌کننده libevent base و یک بخش نشست متعلق به خود دارد؛ ارسال‌های هر تیک درون یک فراخوانی sendmsg مبتنی بر UDP-GSO (یا در صورت عدم دسترسی به GSO، یک sendmmsg) ادغام می‌شوند. حداکثر 4.

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

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

-p: پورت سرور TURN (پیش‌فرض‌ها: 3478 غیرامن، 5349 امن).
-n: تعداد پیام‌ها برای ارسال (پیش‌فرض: 5). در حالت load-generator، گزینه -n تعداد عملیات‌ها به‌ازای هر کلاینت است.

اگر در آنجا حذف شود، کلاینت تا زمان توقف دستی اجرا خواهد شد.

-d: دستگاه رابط محلی (اختیاری، تنها لینوکس).
-L: آدرس IP محلی (اختیاری).
-m: تعداد کلاینت‌ها (پیش‌فرض: 1، 2 یا 4، بسته به گزینه‌ها).
-e: آدرس همتا (peer).
-r: پورت همتا (peer) (پیش‌فرض: 3480).
-z: فاصله زمانی بسته‌ها در هر نشست به میلی‌ثانیه (پیش‌فرض: 20). در حالت‌های load-generator از نوع packet و invalid، مقدار پیش‌فرض 0 میلی‌ثانیه است.

-u: نام کاربری STUN/TURN.
-w: گذرواژه کاربر STUN/TURN.
-W: رمز TURN REST API. عبارت محرمانه به‌صورت «متن خام» (plain text) مانند "north" که در صورت پویا بودن در ستون value جدول turn_secret

در پایگاه‌داده ذخیره می‌شود، یا مقدار static-auth-secret تنظیم‌شده در فایل پیکربندی در صورت استفاده از حالت ایستا.

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

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

نکاتی برای حالت load-generator:

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

مثال‌ها را در دایرکتوری "examples/scripts" مشاهده کنید..SH ======================================

نام (NAME)

turnutils_peer - یک سرور پسانه بازتاب (echo backend) ساده و صرفاً مبتنی بر UDP.

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

$ turnutils_peer [-v] [options]

توضیحات (DESCRIPTION)

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

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

-p: درگاه شنود UDP (پیش‌فرض: 3480).
-d: دستگاه رابط شنود (اختیاری).
-L: نشانی شنود سرور turnutils_peer. می‌توان از چندین نشانی شنود، IPv4 و IPv6، استفاده کرد. اگر هیچ نشانی شنودی تعیین نشود، بر روی تمام نشانی‌های IPv4 و IPv6 گوش می‌دهد.
-v: حالت پرگو (با جزئیات)

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

نام (NAME)

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

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

$ turnutils_stunclient [options] <STUN-Server-IP-address>

توضیحات (DESCRIPTION)

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

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

-p: درگاه سرور STUN (پیش‌فرض: 3478).
-L: نشانی محلی مورد استفاده (اختیاری).
-f: اجبار به پردازش بر اساس RFC 5780.
-c: ارسال مداوم درخواست‌های بایندینگ STUN و گزارش تأخیر رفت‌وبرگشت تا زمان متوقف شدن.
-i: فاصله زمانی بین درخواست‌های متوالی به میلی‌ثانیه (پیش‌فرض: 1000).
-t: مهلت زمانی پاسخ (timeout) به میلی‌ثانیه (پیش‌فرض: 3000).

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

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

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

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

نام (NAME)

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

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

$ turnutils_rfc5769check

توضیحات (DESCRIPTION)

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

کاربرد:

$ turnutils_rfc5769check

=====================================.SS نام (NAME)

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

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

$ turnutils_natdiscovery [options] <STUN-Server-FQDN-or-IP-address>

توضیحات (DESCRIPTION)

ابزار turnutils_natdiscovery رفتار نگاشت (Mapping) و پالایش (Filtering) مربوط به 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 (پیش‌فرض: 3478)
-L: نشانی محلی مورد استفاده (اختیاری)
-l: درگاه محلی مورد استفاده (استفاده همراه با -L)
-A: نشانی محلی ثانویه (اختیاری) برای کشف برخورد الزامی است

-T: زمان‌سنج طول عمر نگاشت (ثانیه) توسط کشف رفتار طول عمر نگاشت استفاده می‌شود

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

$ turnutils_natdiscovery -m -f stun.example.com

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

نام (NAME)

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

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

$ turnutils_oauth [options]

توضیحات (DESCRIPTION)

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

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

پرچم‌ها:

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

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

-i, --server-name: نام سرور (حداکثر ۲۵۵ نویسه)
-j, --auth-key-id: شناسه کلید Auth (حداکثر ۳۲ نویسه)
-k, --auth-key: کلید Auth با کدگذاری base64
-l: --auth-key-timestamp مهر زمانی کلید Auth (ثانیه از مبدأ زمانی epoch)
-m, --auth-key-lifetime: طول عمر کلید Auth به ثانیه
-n, --auth-key-as-rs-alg: الگوریتم رمزنگاری میان Authorization Server(AS) و Resource Server(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: مهر زمانی در قالب ۶۴ بیتی بدون علامت (قالب بومی - یونیکس)، به این صورت که ۴۸ بیت برای ثانیه‌ها از مبدأ زمانی UTC و ۱۶ بیت برای کسرهای ۱/۶۴۰۰۰ ثانیه است.