MOSQUITTO_CTRL(1) Commands MOSQUITTO_CTRL(1)

mosquitto_ctrl - ابزاری برای مقداردهی اولیه یا پیکربندی نمونه کارگزار Mosquitto

mosquitto_ctrl [options | -o config-file] module-name module-command [command-options]

options: [auth-options] [connection-options] [mqtt-options] [output-options] [tls-certificate-options | tls-psk-options]

auth-options:
[-u username] [-P password]

connection-options:
{[-h hostname] [--unix socket path] [-p port-number] | -L URL}
[-A bind-address]
[--proxy socks-url]

mqtt-options:
[-c] [-i client-id] [-q message-QoS] [-V protocol-version]

output-options:
[-d] [--quiet]

tls-certificate-options:
[--no-tls]
{--cafile file | --capath dir}
[--tls-use-os-certs]
[--cert file] [--key file]
[--ciphers ciphers] [--insecure] [--tls-alpn protocol] [--tls-keylog file] [--tls-version version]
[--tls-engine engine] [--keyform {pem | engine}] [--tls-engine-kpass-sha1 kpass-sha1]

tls-psk-options:
--psk hex-key --psk-identity identity [--ciphers ciphers] [--tls-version version]

mosquitto_ctrl [connection-options] (حالت پوسته تعاملی)

mosquitto_ctrl [--help]

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

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

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

جهت فعال‌سازی اتصالات TLS هنگام استفاده از گواهی‌های x509، باید یکی از گزینه‌های --cafile یا --capath به عنوان گزینه مشخص شود.

برای فعال‌سازی اتصالات TLS هنگام استفاده از TLS-PSK، باید از گزینه‌های --psk و --psk-identity استفاده کنید.

امنیت پویا (Dynamic security)

احراز هویت و کنترل دسترسی مبتنی بر نقش به همراه کاربران و گروه‌ها. از نام ماژول dynsec استفاده می‌کند. ببینید: mosquitto_ctrl_dynsec(1)

ماژول‌های خارجی (External modules)

mosquitto_ctrl قابلیت بارگذاری ماژول‌های خارجی در قالب کتابخانه‌های اشتراکی را دارد. برای نمونه، استفاده از نام ماژول example بسته به پلتفرم تلاش می‌کند تا ماژول خارجی mosquitto_ctrl_example.so یا mosquitto_ctrl_example.dll را بارگذاری کند. این امکان اجازه می‌دهد قابلیت‌های جدید با ترکیب یک افزونه و ماژول mosquitto_ctrl به Mosquitto اضافه شوند، بدون نیاز به کامپایل مجدد هیچ بخشی از کد مبدأ Mosquitto.

گزینه‌های زیر را می‌توان در خط فرمان مشخص کرد، اما می‌توان آن‌ها را در یک فایل پیکربندی واقع در مسیر $XDG_CONFIG_HOME/mosquitto_ctrl یا $HOME/.config/mosquitto_ctrl نیز قرار داد.

فایل پیکربندی را می‌توان با گزینه -o config-file به صورت دستی مشخص کرد.

فایل پیکربندی باید در هر خط شامل یک جفت -option value باشد. مقادیر موجود در فایل پیکربندی به عنوان پیش‌فرض استفاده می‌شوند و می‌توان آن‌ها را از طریق خط فرمان بازنویسی کرد. استثنای این قاعده، گزینه‌های نوع پیام هستند که تنها یکی از آن‌ها می‌تواند مشخص شود. همچنین توجه داشته باشید که در حال حاضر برخی گزینه‌ها را نمی‌توان نفی کرد، برای مثال -S. خطوطی از فایل پیکربندی که نویسه نخست آن‌ها # است، به عنوان توضیح در نظر گرفته شده و پردازش نمی‌شوند.

-A

اتصال خروجی را به یک نشانی IP یا نام میزبان محلی مقید (bind) می‌کند. اگر نیاز به محدود کردن ارتباط شبکه به یک رابط خاص دارید، از این آرگومان استفاده کنید.

--cafile

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

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

--capath

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

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

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

--cert

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

همچنین ببینید: --key و بخش اتصالات رمزنگاری‌شده.

--ciphers

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

-d, --debug

پیام‌های اشکال‌زدایی را فعال می‌کند.

-D, --property

ویژگی‌های MQTT v5 را برای این کلاینت تنظیم می‌کند. اگر از این گزینه استفاده کنید، کلاینت در حالت MQTT v5 تنظیم خواهد شد. این گزینه دو ساختار دارد:

-D command identifier value

-D command identifier name value

command شناسه دستور/بسته MQTT است و می‌تواند یکی از مقادیر CONNECT، PUBLISH، PUBACK، PUBREC، PUBCOMP، SUBSCRIBE، UNSUBSCRIBE، DISCONNECT، AUTH یا WILL باشد. ویژگی‌های موجود برای هر دستور در بخش ویژگی‌ها فهرست شده‌اند.

identifier نام ویژگی برای افزودن است. این نام همان‌طور که در مشخصات استاندارد آمده با علامت '-' به عنوان جداکننده کلمات نوشته می‌شود. به عنوان مثال: payload-format-indicator. جزئیات بیشتر در بخش ویژگی‌ها آمده است.

value مقدار ویژگی مورد نظر برای افزودن است، با نوع داده‌ای که وابسته به آن ویژگی است.

name فقط برای ویژگی user-property به عنوان رشته اول در جفت‌رشته استفاده می‌شود. در آن حالت، value رشته دوم در این جفت خواهد بود.

--help

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

-h, --host

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

-i, --id

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

--insecure

هنگام استفاده از رمزنگاری مبتنی بر گواهی، این گزینه بررسی تطابق نام میزبان سرور در گواهی سرور را غیرفعال می‌کند. این ویژگی هنگام آزمایش اولیه‌ی پیکربندی سرور می‌تواند مفید باشد، اما این امکان را فراهم می‌سازد که یک شخص ثالث مخرب برای مثال با جعل DNS (اسپوفینگ) خود را به عنوان سرور شما جا بزند. از این گزینه تنها در آزمایش‌ها استفاده کنید. اگر مجبور به استفاده از این گزینه در یک محیط عملیاتی هستید، راه‌اندازی شما دارای ایراد است و استفاده از رمزنگاری هیچ فایده‌ای نخواهد داشت.

--key

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

همچنین ببینید: --cert و بخش اتصالات رمزنگاری‌شده.

--keyform

نوع کلید خصوصی مورد استفاده هنگام برقراری اتصالات TLS را مشخص می‌کند. این گزینه می‌تواند "pem" یا "engine" باشد. این پارامتر زمانی مفید است که یک ماژول TPM مورد استفاده قرار گرفته و کلید خصوصی با آن ایجاد شده باشد. مقدار پیش‌فرض "pem" است که یعنی از فایل‌های معمولی کلید خصوصی استفاده می‌شود.

همچنین ببینید: --tls-engine.

-L, --url

نام کاربری، گذرواژه، نام میزبان، پورت و موضوع را هم‌زمان به عنوان یک URL مشخص می‌کند. ساختار URL باید به این شکل باشد: mqtt(s)://[username[:password]@]host[:port]/topic یا ws(s)://[username[:password]@]host[:port]/path

بسته به پیشوند، پورت پیش‌فرض مقادیر متفاوتی خواهد داشت: mqtt:// - 1883، mqtts:// - 8883، ws:// - 80، wss:// - 443.

--nodelay

الگوریتم Nagle را برای سوکت غیرفعال می‌کند. این بدان معنی است که تأخیر پیام‌های ارسالی کاهش می‌یابد که این موضوع به ویژه برای پیام‌های کوچک و نسبتاً کم‌تکرار مشهود است. استفاده از این گزینه ممکن است منجر به ارسال بسته‌های بیشتری نسبت به حالت معمول شود.

-o config-file

مسیری را به یک فایل پیکربندی برای بارگذاری گزینه‌ها ارائه می‌دهد. فایل پیکربندی باید در هر سطر شامل یک جفت -option value باشد. مقادیر موجود در فایل پیکربندی به عنوان پیش‌فرض استفاده شده و می‌توانند توسط خط فرمان بازنویسی شوند. استثنای این امر گزینه‌های نوع پیام هستند که تنها یکی از آن‌ها می‌تواند مشخص شود. همچنین توجه داشته باشید که در حال حاضر برخی گزینه‌ها را نمی‌توان نفی کرد؛ به عنوان مثال -S. سطرهایی از فایل پیکربندی که نویسه نخست آن‌ها # است، به عنوان توضیح تلقی شده و پردازش نمی‌شوند.

-p, --port

به پورت مشخص‌شده متصل می‌شود. اگر داده نشود، مقدار پیش‌فرض ۱۸۸۳ برای MQTT ساده یا ۸۸۸۳ برای MQTT از طریق TLS استفاده خواهد شد.

-P, --pw

گذرواژه‌ای برای احراز هویت با کارگزار ارائه می‌دهد. استفاده از این آرگومان بدون مشخص کردن نام کاربری هنگام استفاده از MQTT نسخه‌های v3.1 یا v3.1.1 نامعتبر است.

همچنین گزینه --username را ببینید.

--proxy

یک پروکسی SOCKS5 را برای اتصال از طریق آن مشخص می‌کند. انواع احراز هویت "None" و "username" پشتیبانی می‌شوند. socks-url باید به شکل socks5h://[username[:password]@]host[:port] باشد. پیشوند پروتکل socks5h به این معنی است که نام‌های میزبان توسط پروکسی تحلیل می‌شوند. نویسه‌های %25، %3A و %40 در صورت وجود در نام کاربری یا گذرواژه به ترتیب به %، : و @ رمزگشایی می‌شوند.

اگر نام کاربری داده نشود، هیچ تلاشی برای احراز هویت صورت نمی‌گیرد. اگر پورت داده نشود، مقدار پیش‌فرض ۱۰۸۰ استفاده می‌شود.

اگر میزبان به صورت نشانی IPv6 مشخص شود، باید درون کروشه قرار گیرد؛ مانند socks5h://[::1]:1080. توجه داشته باشید که کروشه‌ها در برخی پوسته‌ها دارای معنای خاصی هستند، بنابراین ممکن است نشانی URL پروکسی نیاز به قرارگیری داخل گیومه تکی یا جفتی داشته باشد.

نسخه‌های بیشتری از SOCKS ممکن است بر اساس تقاضا در آینده در دسترس قرار گیرند و از پیشوندهای پروتکل متفاوتی طبق توضیحات curl(1) استفاده خواهند کرد.

--psk

کلید از پیش به اشتراک گذاشته شده در مبنای ۱۶ (بدون 0x آغازین) منطبق با آنچه در کارگزار استفاده شده است را برای پشتیبانی از رمزنگاری TLS-PSK ارائه می‌دهد. --psk-identity نیز باید برای فعال‌سازی TLS-PSK مشخص شود.

--psk-identity

شناسه کلاینت برای استفاده با پشتیبانی از TLS-PSK. اگر کارگزار برای آن پیکربندی شده باشد، می‌توان از این مقدار به جای نام کاربری استفاده کرد.

-q, --qos

سطح کیفیت خدمات (QoS) را برای پیام‌ها از بین 0، 1 و 2 مشخص می‌کند. پیش‌فرض 1 است.

--quiet

اگر این آرگومان داده شود، هیچ خطای زمان اجرایی چاپ نخواهد شد. این امر پیام‌های خطای مربوط به ورودی نامعتبر کاربر را شامل نمی‌شود (مانند استفاده از --port بدون پورت).

--tls-alpn

پروتکلی را برای استفاده هنگام اتصال به کارگزاری که چندین پروتکل را روی یک پورت در دسترس دارد (مانند MQTT و WebSockets) ارائه می‌دهد.

--tls-engine

یک شناسه معتبر موتور openssl. این شناسه‌ها را می‌توان با دستور openssl engine فهرست کرد.

همچنین ببینید: --keyform.

--tls-engine-kpass-sha1

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

همچنین ببینید: --tls-engine.

--tls-use-os-certs

در صورت استفاده، گواهی‌های CA ارائه‌شده توسط سیستم‌عامل بارگذاری شده و مورد اعتماد قرار می‌گیرند. این گزینه می‌تواند در کنار --cafile و --capath استفاده شود، یا به تنهایی برای فعال کردن حالت TLS به کار رود. اگر از -L mqtts://... استفاده شود یا اگر پورت برابر ۸۸۸۳ باشد و هیچ گزینه گواهی دیگری استفاده نشده باشد، این گزینه به طور پیش‌فرض فعال خواهد شد.

--tls-version

نسخه پروتکل TLS را برای ارتباط با کارگزار انتخاب می‌کند. گزینه‌های معتبر tlsv1.3 و tlsv1.2 هستند. مقدار پیش‌فرض tlsv1.2 است. باید با نسخه پروتکل مورد استفاده کارگزار همخوانی داشته باشد.

-u, --username

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

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

--unix

اتصال به کارگزار از طریق یک سوکت دامنه یونیکس محلی به جای سوکت TCP. این گزینه جایگزینی برای -h و -L است؛ به عنوان مثال: mosquitto_ctrl --unix /tmp/mosquitto.sock ...

گزینه socket_domain را در mosquitto.conf(5) برای پیکربندی Mosquitto جهت گوش دادن به یک سوکت یونیکس ببینید.

-V, --protocol-version

نسخه پروتکل MQTT مورد استفاده هنگام اتصال به کارگزار راه دور را مشخص می‌کند. می‌تواند 5، 311، 31، یا شکل مشروح‌تر mqttv5، mqttv311 یا mqttv31 باشد. مقدار پیش‌فرض 311 است.

گزینه -D / --property امکان افزودن ویژگی‌ها را در مراحل مختلف اجرای mosquitto_ctrl فراهم می‌کند. ویژگی‌های پشتیبانی‌شده برای هر دستور به شرح زیر است:

•authentication-data (داده دودویی - توجه: به عنوان رشته رفتار می‌شود)
•authentication-method (جفت‌رشته UTF-8)
•maximum-packet-size (عدد صحیح بی‌علامت ۳۲ بیتی)
•receive-maximum (عدد صحیح بی‌علامت ۱۶ بیتی)
•request-problem-information (عدد صحیح بی‌علامت ۸ بیتی)
•request-response-information (عدد صحیح بی‌علامت ۸ بیتی)
•session-expiry-interval (عدد صحیح بی‌علامت ۳۲ بیتی؛ توجه: به جای آن از -x استفاده کنید)
•topic-alias-maximum (عدد صحیح بی‌علامت ۱۶ بیتی)
•user-property (جفت‌رشته UTF-8)

•content-type (رشته UTF-8)
•correlation-data (داده دودویی - توجه: به عنوان رشته رفتار می‌شود)
•message-expiry-interval (عدد صحیح بی‌علامت ۳۲ بیتی)
•payload-format-indicator (عدد صحیح بی‌علامت ۸ بیتی)
•response-topic (رشته UTF-8)
•topic-alias (عدد صحیح بی‌علامت ۱۶ بیتی)
•user-property (جفت‌رشته UTF-8)

•session-expiry-interval (عدد صحیح بی‌علامت ۳۲ بیتی)
•user-property (جفت‌رشته UTF-8)

•content-type (رشته UTF-8)
•correlation-data (داده دودویی - توجه: به عنوان رشته رفتار می‌شود)
•message-expiry-interval (عدد صحیح بی‌علامت ۳۲ بیتی)
•payload-format-indicator (عدد صحیح بی‌علامت ۸ بیتی)
•response-topic (رشته UTF-8)
•user-property (جفت‌رشته UTF-8)
•will-delay-interval (عدد صحیح بی‌علامت ۳۲ بیتی)

در صورت موفقیت مقدار صفر و در صورت بروز خطا مقداری غیر صفر بازگردانده می‌شود. اگر اتصال توسط کارگزار در سطح MQTT رد شود، کد خروج همان کد دلیل CONNACK خواهد بود. در صورت بروز هر خطای دیگری، کد خروج مقدار بازگشتی libmosquitto است.

کدهای CONNACK در MQTT نسخه v3.1.1:

•0 موفقیت‌آمیز (Success)
•1 اتصال رد شد: نسخه پروتکل نامعتبر است (Connection refused: Bad protocol version)
•2 اتصال رد شد: شناسه پذیرفته نشد (Connection refused: Identifier rejected)
•3 اتصال رد شد: سرور در دسترس نیست (Connection refused: Server unavailable)
•4 اتصال رد شد: نام کاربری یا گذرواژه نادرست است (Connection refused: Bad username/password)
•5 اتصال رد شد: فاقد مجوز (Connection refused: Not authorized)

کدهای CONNACK در MQTT نسخه v5:

•0 موفقیت‌آمیز (Success)
•128 خطای نامشخص (Unspecified error)
•129 بسته ناقص یا بدشکل (Malformed packet)
•130 خطای پروتکل (Protocol error)
•131 خطای وابسته به پیاده‌سازی (Implementation specific error)
•132 نسخه پروتکل پشتیبانی نمی‌شود (Unsupported protocol version)
•133 شناسه کلاینت نامعتبر است (Client ID not valid)
•134 نام کاربری یا گذرواژه نادرست است (Bad username or password)
•135 فاقد مجوز (Not authorized)
•136 سرور در دسترس نیست (Server unavailable)
•137 سرور مشغول است (Server busy)
•138 مسدود شده (Banned)
•139 سرور در حال خاموش شدن است (Server shutting down)
•140 روش احراز هویت نادرست است (Bad authentication method)
•141 پایان مهلت زنده ماندن (Keep alive timeout)
•142 نشست توسط اتصال دیگری تصاحب شد (Session taken over)
•143 فیلتر موضوع نامعتبر است (Topic filter invalid)
•144 نام موضوع نامعتبر است (Topic name invalid)
•147 سقف دریافت رد شد (Receive maximum exceeded)
•148 نام مستعار موضوع نامعتبر است (Topic alias invalid)
•149 بسته بیش از حد بزرگ است (Packet too large)
•148 نرخ ارسال پیام بیش از حد بالاست (Message rate too high)
•151 سهمیه مصرف تمام شده است (Quota exceeded)
•152 اقدام مدیریتی (Administrative action)
•153 قالب داده بدنه نامعتبر است (Payload format invalid)
•154 نگهداری پیام پشتیبانی نمی‌شود (Retain not supported)
•155 سطح کیفیت خدمات پشتیبانی نمی‌شود (QoS not supported)
•156 از سرور دیگری استفاده کنید (Use another server)
•157 سرور منتقل شده است (Server moved)
•158 اشتراک‌های هم‌رسان پشتیبانی نمی‌شود (Shared subscriptions not supported)
•159 نرخ برقراری اتصال بیش از حد مجاز است (Connection rate exceeded)
•160 حداکثر زمان مجاز اتصال (Maximum connect time)
•161 شناسه‌های اشتراک پشتیبانی نمی‌شود (Subscription IDs not supported)
•162 اشتراک‌های با نویسه عمومی پشتیبانی نمی‌شود (Wildcard subscriptions not supported)

سایر کدها:

•27 پایان مهلت انتظار برای دریافت پیام (Timed out waiting for message)

MOSQUITTO_UNSAFE_ALLOW_SYMLINKS

به طور پیش‌فرض، از بارگذاری فایل‌های حساس که مسیر آن‌ها شامل یک پیوند نمادین (symlink) باشد خودداری خواهد شد. این متغیر محیطی را روی هر مقداری تنظیم کنید تا بارگذاری فایل‌ها از طریق پیوندهای نمادین مجاز گردد. توجه داشته باشید که بهره‌گیری از این متغیر می‌تواند شما را در معرض حملات پیوند نمادین قرار دهد و بنابراین فقط در مواردی باید استفاده شود که کاملاً مطمئن هستید چنین خطری وجود ندارد.

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

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

Roger Light <roger@atchoo.org>

04/03/2026 Mosquitto Project