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

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

1.: turnutils_uclient: چندین کلاینت UDP، TCP، TLS یا DTLS را شبیه‌سازی می‌کند. (این برنامه صرفاً برای اهداف آزمایشی ارائه شده است!) تصویر باینری کامپایل‌شدهٔ این برنامه در زیرشاخهٔ bin/ قرار دارد.
2.: turnutils_peer: یک سرور سادهٔ بدون‌وضعیت (stateless) و فقط-UDP از نوع «echo»، برای استفاده به عنوان سرور نهایی در الگوی بازپخش (relay موسوم به «peer»). این سرور برای هر بستهٔ ورودی UDP، صرفاً آن را بازمی‌فرستد (echo می‌کند). (این برنامه صرفاً برای اهداف آزمایشی ارائه شده است!) هنگامی که کلاینت‌های آزمایشی به صورت کلاینت-به-کلاینت (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 است که باید به کلاینت منتقل شوند. خروجی بر اساس RFC7635 پیوست B، شکل 8 تولید می‌شود.

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

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

نام (NAME)

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

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

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

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

پرچم‌ها:

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

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

-P: حالت Passive 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 Channels استفاده می‌کند.
-y: استفاده از اتصالات کلاینت به کلاینت (client-to-client): جفت کانال 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 Mobility.
-I: عدم تنظیم مجوزها بر روی نقاط پایانی رله‌ی TURN (جهت آزمایش کارکرد غیر استاندارد رله‌ی سرور).

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

زیرحالت alloc تخصیص‌ها را با حداکثر سرعت ممکن ایجاد می‌کند، و زیرحالت invalid بسته‌های کوچک نامعتبر را با بیشترین سرعت به شنونده‌ی TURN می‌فرستد. حالت‌های تولید بار مستلزم -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 در دسترس است). مقدار پیش‌فرض auto: مقدار 0 برای -m < 4، که ارتقا می‌یابد به 1

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

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

رفتار سنتی ارسال تک‌ریسمانی را حفظ می‌کند (تابع timer_handler در ریسمان اصلی روی تمام نشست‌ها پیمایش می‌کند). هر ارسال‌کننده پایه‌ی libevent و شارد نشست اختصاصی خود را دارد؛ ارسال‌های در هر تیک در یک sendmsg از نوع UDP-GSO (یا یک sendmmsg در صورت عدم دسترسی به GSO) ادغام می‌شوند. حداکثر 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: پورت همتا (پیش‌فرض: 3480).
-z: فاصلهٔ زمانی ارسال بسته‌ها بر حسب میلی‌ثانیه برای هر نشست (پیش‌فرض: 20). در حالت‌های load-generator بسته (packet) و نامعتبر (invalid)، مقدار پیش‌فرض 0 میلی‌ثانیه است.

-u: نام کاربری STUN/TURN.
-w: گذرواژهٔ کاربر STUN/TURN.
-W: کلید مخفی (secret) مربوط به TURN REST API. رمز «متن خام» مانند “north” که در صورت پویا بودن در ستون value از جدول turn_secret

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

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

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

نکات مربوط به حالت load-generator:

حالت packet همچنان تخصیص/راه‌اندازی معمول TURN را انجام می‌دهد و سپس بی‌درنگ و بدون تنظیم آهنگ ارسال (no 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: پُرگویی (Verbose).

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

نام (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: ارسال مداوم درخواست‌های انقیاد (binding) پروتکل STUN و گزارش تاخیر رفت و برگشت تا زمان توقف.
-i: فاصله زمانی بین درخواست‌های متوالی به میلی‌ثانیه (پیش‌فرض: 1000).
-t: مهلت زمانی پاسخ به میلی‌ثانیه (پیش‌فرض: 3000).

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

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

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

نام (NAME)

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

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

$ turnutils_rfc5769check

توضیحات (DESCRIPTION)

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

کاربرد:

$ turnutils_rfc5769check

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

نام (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 از فیلترسازی‌های Endpoint-Independent، Address-Dependent یا Address and Port-Dependent بهره می‌برد یا خیر.

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

پرچم‌ها:

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

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

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

-p: درگاه سرور STUN (پیش‌فرض: 3478)
-L: نشانی محلی مورد استفاده (اختیاری)
-l: درگاه محلی مورد استفاده (همراه با -L استفاده شود)
-A: نشانی محلی ثانویه (اختیاری) برای کشف برخورد (collision) الزامی است

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

کاربرد:

$ turnutils_natdiscovery -m -f stun.example.com.SH =====================================

نام (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 است که باید به کلاینت تحویل داده شوند. خروجی مطابق با RFC7635، پیوست B، شکل ۸ تولید می‌شود. این ابزار می‌تواند به ساخت یک سرویس Auth Server کمک کند، اما توجه داشته باشید که این ابزار «session key» / «mac_key» تولید نمی‌کند و طول‌عمر «session key» / «mac_key» یا «Auth key» را نیز اعتبارسنجی نمی‌نماید. برای جزئیات بیشتر و ساختار access_token، سند rfc7635 را مطالعه کرده و مثال موجود در examples/scripts/oauth.sh را ببینید.

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

پرچم‌ها:

-h, --help: راهنمای استفاده
-v, --verbose: حالت پرگو (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: برچسب زمانی در قالب ۶۴ بیتی بدون علامت (قالب بومی - Unix)، به این صورت که ۴۸ بیت برای ثانیه‌ها از مبدأ زمان UTC به علاوهٔ ۱۶ بیت برای کسرهای ۱/۶۴۰۰۰ ثانیه.

برای مثال: unixtimestamp واقعی ۱۶ بیت به چپ شیفت داده شده است. (پیش‌فرض: gmtime واقعی)

-r, --token-lifetime: طول‌عمر به ثانیه (پیش‌فرض: 3600)
-t, --token: توکن رمزنگاری‌شدهٔ کدگذاری‌شده با base64 برای اعتبارسنجی و رمزگشایی
-u, --hmac-alg: الگوریتم hmac کلاینت stun