نام (NAME)

mosquitto_ctrl_shell - یک پوسته تعاملی برای پیکربندی نمونه کارگزار Mosquitto

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

mosquitto_ctrl [-h hostname] [-p port-number] [-u username] [-P password] [-i client-id] [--cafile file] [--capath dir] [--cert file --key file]

توضیحات (DESCRIPTION)

mosquitto_ctrl ابزاری برای کمک به پیکربندی یک نمونه کارگزار Mosquitto است.

این صفحه راهنما نحوه استفاده از پوسته تعاملی را شرح می‌دهد. برای کسب اطلاعات درباره حالت صرفاً خط فرمانی، mosquitto_ctrl(1) را ببینید. پوسته تعاملی اکثر عملیات‌ها را بسیار ساده و مستقیم می‌سازد و برای سهولت استفاده توصیه می‌شود.

برای اجرا در حالت تعاملی، mosquitto_ctrl را بدون هیچ ماژول یا دستوری اجرا کنید؛ یعنی حداکثر همراه با مجموعه‌ای از گزینه‌هایی که در خلاصه دستور بالا توضیح داده شده است. پوسته شروع به کار خواهد کرد و یک اعلان (prompt) به شما نمایش داده می‌شود.

اتصالات رمزنگاری‌شده (ENCRYPTED CONNECTIONS)

mosquitto_ctrl از اتصالات رمزنگاری‌شده TLS پشتیبانی می‌کند. اکیداً توصیه می‌شود برای تمام موارد استفاده از راه دور از mosquitto_ctrl، از یک اتصال رمزنگاری‌شده استفاده کنید.

برای فعال‌سازی اتصالات TLS، با استفاده از شیوه‌نامه (scheme) mqtts:// یا wss:// در داخل پوسته متصل شوید، یا هنگام اجرای mosquitto_ctrl در خط فرمان از گزینه --cafile یا --capath استفاده کنید - این کار همچنین اجازه می‌دهد از گواهی‌های سفارشی CA استفاده شود.

برای امنیت بیشتر می‌توان از گواهی‌های کلاینت نیز استفاده کرد. برای فعال‌سازی این مورد، از گزینه‌های --cert و --key استفاده نمایید.

گردش کار نمونه در پوسته (EXAMPLE SHELL WORKFLOW)

مثال 1.

گردش کار معمول برای استفاده از پوسته تعاملی بدین صورت است که ابتدا احراز هویت را پیکربندی کرده و به یک کارگزار متصل شوید، سپس به حالت (mode) مورد نظر خود رفته و دستورهای آن را اجرا نمایید. به عنوان مثال، برای ایجاد یک گروه جدید در افزونه dynamic-security:

$ mosquitto_ctrl
mosquitto_ctrl shell v2.1.0
> auth
username: admin
password:
> connect mqtt://localhost
mqtt://localhost:1883> dynsec
mqtt://localhost:1883|dynsec> createGroup newgroup
OK

پوسته تعاملی در مجموعه‌ای از حالت‌های مختلف عمل می‌کند که هر کدام دستورهای متفاوتی در دسترس دارند. پوسته در صورت امکان از تکمیل خودکار با کلید تب (tab completion) برای دستورها و آرگومان‌های آن‌ها پشتیبانی می‌کند. معمولاً باید امکان‌پذیر باشد که با دو بار فشردن کلید تب، فهرستی از دستورها یا آرگومان‌های در دسترس فعلی نمایش داده شود.

پوسته دارای تاریخچه‌ای از دستورها است که با فشردن کلیدهای جهت‌نمای بالا و پایین قابل دسترسی است. این تاریخچه بر روی دیسک ذخیره نمی‌شود.

راهنمای هر دستور را می‌توان با وارد کردن help به همراه نام دستور به دست آورد. برای مثال: help createGroup.

حالت‌های مختلف عبارتند از:

Pre-connection

در این حالت امکان تنظیم مشخصات احراز هویت، اتصال به یک broker، خواندن راهنما و خروج وجود دارد.

Post-connection

در این حالت، mosquitto_ctrl به یک broker متصل است و می‌توانید بین ماژول‌های کنترلی مختلف جابه‌جا شوید، راهنما را مشاهده کنید یا خارج شوید.

dynsec

امکان ایجاد، حذف و ویرایش کاربران، گروه‌ها، نقش‌ها و ACLها را به شما می‌دهد.

broker

امکان مشاهده اطلاعات listener و افزونه‌ها (plugins) را به شما می‌دهد.

احراز هویت (AUTHENTICATION)

mosquitto_ctrl از احراز هویت با نام کاربری و گذرواژه، یا از طریق گواهی‌های کلاینت x509 پشتیبانی می‌کند. اگر از احراز هویت با نام کاربری و گذرواژه استفاده می‌کنید، باید پیش از اتصال، نام کاربری و گذرواژه را تنظیم کنید. این کار را می‌توان به یکی از دو روش انجام داد. روش نخست استفاده از گزینه‌های -u و -P در خط فرمان است. روش دوم استفاده از دستور auth در پوسته است.

احراز هویت در پوسته می‌تواند به یکی از دو روش انجام شود. روش نخست استفاده از دستور auth است که سپس نام کاربری و گذرواژه را درخواست می‌کند. روش دوم استفاده از دستور auth username است که سپس گذرواژه را درخواست می‌کند.

اتصال (CONNECTION)

برای اتصال به یک broker، از دستور connect استفاده کنید.

•اتصال به broker در localhost روی پورت 1883.

> connect

•اتصال به یک broker مشخص با استفاده از پورت پیش‌فرض 1883.

> connect mqtt://test.mosquitto.org

•اتصال به یک broker مشخص با استفاده از پورت مشخص 1884.

> connect mqtt://test.mosquitto.org:1884

•اتصال به یک broker مشخص با استفاده از TLS.

> connect mqtts://test.mosquitto.org

•اتصال به یک broker مشخص با استفاده از websockets.

> connect ws://test.mosquitto.org

•اتصال به یک broker مشخص با استفاده از websockets بر بستر TLS.

> connect wss://test.mosquitto.org

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

حالت امنیت پویا (DYNAMIC-SECURITY MODE)

پس از اتصال، می‌توانید از دستور dynsec برای رفتن به حالت امنیت پویا استفاده کنید. این کار تنها در صورتی عمل خواهد کرد که کارگزار افزونهٔ dynamic-security را بارگذاری کرده باشد و شما دسترسی لازم برای استفاده از آن را داشته باشید.

حالت امنیت پویا دستوراتی برای ایجاد، حذف و ویرایش کاربران، گروه‌ها، نقش‌ها و ACLها دارد. این دستورات را می‌توان با دو بار فشردن کلید Tab مشاهده کرد. برای دستورات مربوطه، نام‌های کاربری، نام‌های گروه و نام‌های نقش را می‌توان با فشردن کلید Tab به‌طور خودکار تکمیل کرد. راهنمای هر دستور با استفاده از help به همراه نام دستور در دسترس است.

برای خروج از حالت امنیت پویا، از دستور return استفاده کنید، یا دستور exit را برای خروج از پوسته به کار ببرید.

حالت کارگزار (BROKER MODE)

از دستور broker برای تغییر وضعیت به حالت کارگزار استفاده کنید. این کار تنها در صورتی عمل خواهد کرد که گزینهٔ enable_control_api در کارگزار روی true تنظیم شده باشد.

حالت کارگزار شامل دستورهای listListeners برای نمایش پیکربندی شنونده‌های فعال، و listPlugins برای نمایش افزونه‌های بارگذاری‌شده کنونی است.

برای خروج از حالت کارگزار، از دستور return استفاده کنید، یا دستور exit را برای خروج از پوسته به کار ببرید.

گزینه‌های اتصال (CONNECTION OPTIONS)

گزینه‌های زیر می‌توانند در خط فرمان مشخص شوند:

--cafile

مسیر فایلی شامل گواهی‌های CA معتبر با کدگذاری PEM را مشخص می‌کند. برای فعال‌سازی ارتباط SSL به کار می‌رود.

همچنین ببینید: --capath

--capath

مسیر پوشه‌ای حاوی گواهی‌های CA معتبر با کدگذاری PEM را مشخص می‌کند. برای فعال‌سازی ارتباط SSL به کار می‌رود.

برای این که --capath به‌درستی کار کند، فایل‌های گواهی باید پسوند «.crt» داشته باشند و باید با هر بار اضافه یا حذف کردن یک گواهی، دستور «openssl rehash <path to capath>» را اجرا کنید.

همچنین ببینید: --cafile

--cert

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

همچنین ببینید: --key و بخش Encrypted Connections.

--ciphers

فهرستی سازگار با openssl از رمزهای TLS جهت پشتیبانی در کلاینت. برای اطلاعات بیشتر ciphers(1) را ببینید.

--help

نمایش اطلاعات نحوه استفاده.

-h, --host

میزبان مورد نظر برای اتصال را مشخص می‌کند. پیش‌فرض localhost است.

-i, --id

شناسهٔ مورد استفاده برای این کلاینت. در صورت تعیین نشدن، یک شناسهٔ کلاینت بر اساس نسخهٔ MQTT مورد استفاده تولید خواهد شد. برای نسخه‌های v3.1.1/v3.1، کلاینت شناسه‌ای با قالب mosq-XXXXXXXXXXXXXXXXXX ایجاد می‌کند که در آن Xها با نویسه‌های حرفی-عددی تصادفی جایگزین می‌شوند. برای نسخهٔ v5.0، کلاینت شناسه‌ای با طول صفر می‌فرستد و کارساز شناسه‌ای برای کلاینت تولید خواهد کرد.

--key

مسیر فایلی شامل یک کلید خصوصی با کدگذاری PEM را برای این کلاینت جهت برقراری TLS دوطرفه با کارساز مشخص می‌کند.

همچنین ببینید: --cert و بخش Encrypted Connections.

-p, --port

به درگاه مشخص‌شده متصل می‌شود. در صورت تعیین نشدن، مقدار پیش‌فرض 1883 برای MQTT معمولی یا 8883 برای MQTT بر بستر TLS استفاده خواهد شد.

-u, --username

یک نام کاربری برای احراز هویت در کارگزار تعیین می‌کند.

همچنین آرگومان --pw را ببینید.

mosquitto_ctrl در صورت موفقیت صفر، یا در صورت بروز خطا مقداری غیرصفر بازمی‌گرداند.

گزارش باگ‌ها (BUGS)

اطلاعات مربوط به باگ‌های mosquitto را می‌توان در نشانی زیر یافت: https://github.com/eclipse-mosquitto/mosquitto/issues

همچنین ببینید (SEE ALSO)

mosquitto(7), mqtt(7), mosquitto_ctrl(1), mosquitto_rr(1), mosquitto_pub(1), mosquitto_sub(1), mosquitto(8), libmosquitto(3), mosquitto-tls(7)

نویسندگان (AUTHORS)

Roger Light <roger@atchoo.org>