MOSQUITTO_RR(1) Commands MOSQUITTO_RR(1)

mosquitto_rr - کلاینت MQTT نسخهٔ 5/3.1.1 برای پیام‌رسانی درخواست/پاسخ

mosquitto_rr [options] -e response-topic -t message-topic... {payload-options}

options:
[auth-options] [connection-options] [misc-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] [--nodelay] [-S] [--ws] [--proxy socks-url]

misc-options:
[--latency] [-o config-file] [-W message-processing-timeout]

mqtt-options:
[-c] [-D command identifier value] [-i client-id] [-I client-id-prefix] [-k keepalive-time] [-q message-QoS] [--retain-handling always | new | never] [-V protocol-version] [-x session-expiry-interval]
[--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]]

output-options:
[-d] [-N] [--pretty] [--quiet] [-R] [-v]

payload-options:
-f file | -m message | -n | -s

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_rr [--help]

mosquitto_rr یک کلاینت MQTT نسخهٔ 5/3.1.1 است که می‌توان از آن برای انتشار پیام درخواست و انتظار برای دریافت پاسخ استفاده کرد. هنگام استفاده از MQTT v5 که پیش‌فرض است، mosquitto_rr از قابلیت Request-Response استفاده خواهد کرد.

گزینه‌های مهم عبارتند از -t، -e و یکی از گزینه‌های -f، -m، -n و -s.

مثال: mosquitto_rr -t request-topic -e response-topic -m message

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

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

همچنین، در صورتی که از گزینهٔ -p 8883 استفاده شود، گواهی‌های ارائه‌شده توسط سیستم‌عامل بارگذاری خواهند شد و نیازی به هیچ‌یک از گزینه‌های --cafile یا --capath نخواهد بود.

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

سه روش برای تعیین گزینه‌ها در mosquitto_rr وجود دارد: فایل پیکربندی پیش‌فرض، یک فایل پیکربندی مشخص‌شده، یا گزینه‌ها در خط فرمان.

فایل پیکربندی پیش‌فرض در سیستم‌های پوزیکس (POSIX) در مسیر $XDG_CONFIG_HOME/mosquitto_rr یا $HOME/.config/mosquitto_rr و در ویندوز در مسیر %USERPROFILE%\mosquitto_rr قرار دارد.

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

خطوطی از فایل پیکربندی که اولین نویسهٔ آن‌ها # باشد، به‌عنوان توضیح (کامنت) در نظر گرفته شده و پردازش نمی‌شوند.

پیشنهاد می‌شود که فایل‌های پیکربندی عمدتاً برای اهداف احراز هویت استفاده شوند. استفاده از یک فایل پیکربندی به شما اجازه می‌دهد بدون نیاز به نمایش نام کاربری و گذرواژه در خط فرمان، احراز هویت را انجام دهید.

از نسخهٔ 2.1 در دسترس است.

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

قالب آن دقیقاً همانند فایل پیکربندی پیش‌فرض است.

-A

پیوند دادن اتصال خروجی به یک نشانی IP یا نام میزبان محلی. در صورتی که نیاز به محدود کردن ارتباطات شبکه به یک رابط شبکهٔ خاص دارید از این آرگومان استفاده کنید.

-c, --disable-clean-session

غیرفعال کردن 'clean session' / فعال کردن حالت کلاینت ماندگار (persistent client mode). هنگامی که از این آرگومان استفاده شود، به کارگزار (broker) دستور داده می‌شود که هنگام اتصال کلاینت، نشست‌های موجود برای همان شناسهٔ کلاینت (client id) را پاک نکند، و نشست‌ها با قطع ارتباط کلاینت هرگز منقضی نخواهند شد. کلاینت‌های MQTT نسخهٔ ۵ می‌توانند فاصلهٔ زمانی انقضای نشست خود را با آرگومان -x تغییر دهند.

هنگامی که یک نشست روی کارگزار ماندگار شود، اشتراک‌های کلاینت پس از قطع ارتباط، به همراه پیام‌های بعدی QoS 1 و QoS 2 که دریافت می‌شوند حفظ خواهند شد. با اتصال مجدد کلاینت و در صورتی که نشست پاک نشود، تمام پیام‌های صف‌بندی‌شده را دریافت خواهد کرد.

در صورت استفاده از این گزینه، شناسهٔ کلاینت باید به‌صورت دستی با --id تنظیم شود.

--cafile

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

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

--capath

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

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

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

--cert

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

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

--ciphers

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

-d, --debug

فعال‌سازی پیام‌های اشکال‌زدایی (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 باشد. ویژگی‌های موجود برای هر دستور در بخش ویژگی‌ها (Properties) فهرست شده‌اند.

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

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

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

-e

موضوع پاسخ (response topic). کلاینت برای منتظر ماندن جهت دریافت پاسخ، در این موضوع مشترک خواهد شد.

-f, --file

ارسال محتویات یک فایل به‌عنوان پیام.

-F

مشخص کردن قالب چاپ خروجی. این گزینه به شما امکان می‌دهد انتخاب کنید چه اطلاعاتی از هر پیام بر روی صفحه چاپ شود. برای جزئیات کامل، بخش قالب خروجی (Output Format) را در زیر مشاهده کنید.

این گزینه بر گزینهٔ -v اولویت دارد، اما جایگزین گزینهٔ -N نمی‌شود.

--help

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

-h, --host

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

-i, --id

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

-I, --id-prefix

پیشوندی ارائه می‌دهد که شناسهٔ کلاینت با الحاق شناسهٔ فرایند (PID) کلاینت به انتهای آن ساخته می‌شود. این گزینه زمانی مفید است که کارگزار از گزینهٔ clientid_prefixes استفاده می‌کند. نمی‌توان آن را هم‌زمان با آرگومان --id استفاده کرد.

--insecure

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

-k, --keepalive

تعداد ثانیه‌های بین ارسال دستورات PING به کارگزار به‌منظور مطلع ساختن آن از اتصال و عملکرد صحیح ما. پیش‌فرض ۶۰ ثانیه است.

--key

تعیین مسیر فایلی حاوی یک کلید خصوصی با کدگذاری PEM برای این کلاینت، جهت انجام TLS دوطرفه (mutual TLS) با سرور.

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

--keyform

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

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

-L, --url

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

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

از نسخهٔ 2.1 موجود است.

اگر این گزینه مشخص شود، mosquitto_rr تاخیر بین شروع انتشار درخواست و رسیدن پاسخ را چاپ خواهد کرد. این عدد شامل زمان‌های پردازش کارگزار و کلاینت، و همچنین هرگونه تاخیر ذاتی شبکه است.

می‌توان از این قابلیت برای اندازه‌گیری بسیار سادهٔ تاخیر تحویل پیام با تعیین یک موضوع (topic) یکسان برای درخواست و پاسخ استفاده کرد.

هنگام استفاده از --latency، گزینهٔ --nodelay به‌طور خودکار استفاده خواهد شد.

-m, --message

ارسال یک پیام درخواست تکی از خط فرمان.

-N

عدم افزودن نویسهٔ پایان خط به بار داده (payload) هنگام چاپ. این کار امکان جاری‌سازی داده‌های بار داده از چندین پیام را به‌طور مستقیم و بدون تغییر به برنامه‌ای دیگر فراهم می‌کند. تنها زمانی که از -v استفاده نشود واقعاً معنادار است.

-n, --null-message

ارسال یک پیام تهی (طول صفر).

--nodelay

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

--no-tls

از نسخهٔ 2.1 موجود است.

غیرفعال کردن تمام موارد استفاده از رمزنگاری TLS. این در صورتی مفید است که گزینه‌های TLS را در یک فایل پیکربندی مشخص کرده باشید اما بخواهید آن گزینه‌ها را غیرفعال کنید. همچنین استفادهٔ خودکار از TLS را هنگام اتصال به درگاه 8883 متوقف می‌کند.

-o config-file

از نسخهٔ 2.1 موجود است.

بارگیری گزینه‌ها از یک فایل پیکربندی. بخش‌های Default Config File و Config File را در ابتدای بخش گزینه‌ها ببینید.

-p, --port

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

-P, --pw

ارائهٔ گذرواژه‌ای برای استفاده در احراز هویت با کارگزار. استفاده از این آرگومان بدون تعیین نام کاربری هنگام استفاده از MQTT نسخهٔ 3.1 یا 3.1.1 نامعتبر است.

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

--pretty

هنگام استفاده از قالب خروجی JSON یعنی %j یا %J، پیش‌فرض چاپ به‌صورت قالب‌بندی‌نشده است. مشخص کردن --pretty پیام‌ها را در قالبی زیباتر و خواناتر برای انسان چاپ می‌کند.

--proxy

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

اگر نام کاربری داده نشود، تلاشی برای احراز هویت انجام نمی‌شود. اگر درگاه داده نشود، پیش‌فرض 1080 استفاده خواهد شد.

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

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

--psk

ارائهٔ کلید از پیش اشتراک‌گذاشته‌شده (pre-shared-key) در مبنای شانزده (بدون 0x در ابتدا) منطبق بر کلید استفاده‌شده در کارگزار جهت استفاده از پشتیبانی رمزنگاری TLS-PSK. برای فعال‌سازی TLS-PSK باید --psk-identity نیز ارائه شود.

--psk-identity

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

-q, --qos

تعیین کیفیت خدمات (QoS) مورد نظر برای پیام‌های دریافتی، از میان 0، 1 و 2. پیش‌فرض 0 است. برای اطلاعات بیشتر دربارهٔ QoS به mqtt(7) مراجعه کنید.

این QoS برای تمام موضوعاتی که در یک نمونهٔ تکی از این کلاینت مشترک شده‌اند اعمال می‌شود.

--quiet

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

-R

اگر این آرگومان داده شود، پیام‌های دریافتی که بیت retain آن‌ها تنظیم شده است چاپ نخواهند شد. پیام‌های دارای retain تنظیم‌شده «کهنه» هستند، از این جهت که معلوم نیست در ابتدا چه زمانی منتشر شده‌اند. هنگام اشتراک در یک موضوع عامه‌منظور (wildcard)، ممکن است تعداد زیادی پیام نگه‌داشته‌شده وجود داشته باشد. این آرگومان نمایش آن‌ها را متوقف می‌کند.

همچنین --retain-handling را ببینید.

--retain-handling always | new | never

از نسخهٔ 2.1 موجود است.

از این گزینه برای کنترل نحوهٔ مدیریت نگه‌داری (retain handling) هنگام ایجاد اشتراک استفاده کنید. این گزینه کنترل می‌کند که یک پیام نگه‌داشته‌شدهٔ (retained) موجود تحت چه شرایطی هنگام اشتراک به کلاینت فرستاده شود.

•always - همیشه پیام‌های نگه‌داشته‌شده تحویل داده شوند
•new - پیام‌های نگه‌داشته‌شده در اولین باری که اشتراک ایجاد می‌شود تحویل داده شوند، اما در اشتراک‌های بعدی خیر. این گزینه برای حالتی مفید است که کلاینتی با اجرای طولانی‌مدت دارید که از یک نشست غیرپاک (non-clean session) استفاده می‌کند. اگر اتصال برای مدت کوتاهی قطع شود، هنگام اتصال مجدد کلاینت، پیام‌های نگه‌داشته‌شده را دوباره دریافت نخواهید کرد.
•never - هرگز پیام‌های نگه‌داشته‌شده تحویل داده نشوند

-S

استفاده از جستجوهای SRV برای تعیین میزبان جهت اتصال به آن. در صورت استفاده در ترکیب با -h، جستجوها را برای _mqtt._tcp.<host> انجام می‌دهد، در غیر این صورت از _mqtt._tcp.<local dns domain> استفاده می‌کند.

-s, --stdin-file

ارسال یک پیام درخواست خوانده‌شده از stdin، با ارسال کل محتوا به‌صورت یک پیام تکی.

-t, --topic

موضوع (topic) در MQTT که پیام درخواست به آن ارسال خواهد شد.

--tls-alpn

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

--tls-engine

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

همچنین --keyform را ببینید. --tls-engine-kpass-sha1

هش SHA1 گذرواژهٔ کلید خصوصی هنگام استفاده از یک موتور TLS. برخی از موتورهای TLS مانند موتور TPM ممکن است برای دسترسی نیازمند گذرواژه باشند. این گزینه اجازه می‌دهد هش SHA1 کدگذاری‌شده در مبنای ۱۶ (hex) گذرواژه مستقیماً به موتور ارسال شود، به جای اینکه از کاربر درخواست گذرواژه شود.

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

--tls-keylog file

موجود از نسخهٔ 2.1 به بعد.

ثبت اطلاعات اتصال TLS در file. این گزینه به ابزارهایی مانند tcpdump، wireshark و mqttshark اجازه می‌دهد ترافیک TLS را رمزگشایی کرده و ترافیک MQTT را بازرسی کنند. در Wireshark این کار می‌تواند با تنظیم گزینهٔ (Pre)-Master-Secret log filename برای پروتکل Transport Layer Security انجام شود.

این گزینه فقط باید برای اشکال‌زدایی استفاده شود، و نباید در محیط عملیاتی به کار رود.

--tls-use-os-certs

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

--tls-version

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

-u, --username

ارائهٔ یک نام کاربری برای احراز هویت با کارگزار.

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

--unix

اتصال به کارگزار از طریق یک سوکت دامنهٔ یونیکس (unix domain socket) محلی به جای سوکت TCP. این یک جایگزین برای -h و -L است. برای مثال: mosquitto_pub --unix /tmp/mosquitto.sock ...

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

-v, --verbose

چاپ پیام‌های دریافت شده با جزئیات کامل (verbose). با این آرگومان، پیام‌ها به صورت "topic payload" چاپ خواهند شد. وقتی این آرگومان داده نشود، پیام‌ها به صورت "payload" چاپ می‌شوند.

همچنین ببینید -F.

-V, --protocol-version

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

-W

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

--will-payload

مشخص کردن پیامی که توسط کارگزار ذخیره شده و در صورتی که اتصال این کلاینت به‌طور غیرمنتظره قطع شود ارسال خواهد شد. این گزینه باید همراه با --will-topic استفاده شود.

--will-qos

سطح کیفیت خدمات (QoS) مورد استفاده برای پیام وصیت (Will). پیش‌فرض 0 است. این گزینه باید همراه با --will-topic استفاده شود.

--will-retain

در صورت تعیین، اگر کلاینت به‌طور غیرمنتظره قطع شود، پیام ارسال‌شده به عنوان یک پیام ماندگار (retained message) در نظر گرفته خواهد شد. این گزینه باید همراه با --will-topic استفاده شود.

--will-topic

موضوعی (topic) که در صورت قطع اتصال غیرمنتظرهٔ کلاینت، پیام وصیت (Will) روی آن ارسال خواهد شد.

--ws

اتصال با استفاده از وب‌سوکت‌ها (WebSockets) به جای TCP ساده.

-x

تنظیم مشخصهٔ session-expiry-interval روی بستهٔ CONNECT. اگر از این گزینه استفاده کنید، کلاینت به عنوان یک کلاینت MQTT v5 تنظیم خواهد شد. برای مشخص کردن اینکه نشست (session) پس از قطع اتصال کلاینت تا چند ثانیه بعد منقضی شود، آن را بین 0-4294967294 تنظیم کنید، یا از -1، 4294967295 یا ∞ برای نشستی که هرگز منقضی نمی‌شود استفاده کنید. در صورتی که -c نیز مشخص شده باشد، پیش‌فرض -1 و در صورت عدم تعیین -c برابر با 0 است.

اگر نشست طوری تنظیم شده باشد که هرگز منقضی نشود (خواه با -x یا با -c)، باید یک شناسهٔ کلاینت (client id) ارائه گردد.

سه روش برای قالب‌بندی خروجی چاپ‌شده وجود دارد. در تمام حالات، یک نویسهٔ خط‌جدید (newline) به ازای هر پیام دریافت‌شده اضافه می‌شود، مگر اینکه آرگومان -N داده شده باشد.

حالت «فقط بار داده» (Payload-only) قالب خروجی پیش‌فرض است و بار داده (payload) را دقیقاً همان‌گونه که دریافت شده است چاپ می‌کند.

حالت پرگو (verbose) با -v فعال می‌شود و موضوع (topic) پیام و بار داده را، جداشده با یک فاصله، چاپ می‌کند.

گزینهٔ نهایی خروجی قالب‌بندی‌شده است که به کاربر اجازه می‌دهد یک قالب خروجی سفارشی تعیین کند. این رفتار با گزینهٔ -F format-string کنترل می‌شود. رشتهٔ قالب (format string) یک رشته متنی آزاد است که در آن دنباله‌های تفسیری با پارامترهای مختلف جایگزین می‌شوند. دنباله‌های تفسیری موجود در زیر شرح داده شده‌اند.

سه نویسه برای شروع یک دنبالهٔ تفسیری استفاده می‌شوند: %، @ و \. دنباله‌هایی که با % آغاز می‌شوند یا پارامترهای مربوط به پیام MQTT در حال چاپ هستند، یا دنباله‌های کمکی هستند تا برای مثال از لزوم نوشتن رشته‌های طولانی قالب تاریخ جلوگیری شود. دنباله‌هایی که با @ آغاز می‌شوند به تابع strftime(3) منتقل می‌شوند (با جایگزین شدن @ با یک % - توجه داشته باشید که تنها نویسهٔ بلافاصله پس از @ به strftime فرستاده می‌شود). این قابلیت امکان ساخت طیف گسترده‌ای از خروجی‌های مبتنی بر زمان را فراهم می‌کند. گزینه‌های خروجی strftime از سکویی به سکوی دیگر متفاوت است، بنابراین لطفاً موارد موجود برای سکوی خود را بررسی کنید. یک افزونه برای strftime ارائه شده است که @N می‌باشد و می‌توان از آن برای به‌دست آوردن تعداد نانوثانیه‌های سپری‌شده از ثانیهٔ فعلی استفاده کرد. تفکیک‌پذیری (resolution) این گزینه بسته به سکو متغیر است. آخرین نویسهٔ دنباله \ است که برای وارد کردن برخی نویسه‌ها به کار می‌رود که در غیر این صورت درج آن‌ها دشوار می‌بود.

پارامترهای %A، %C، %d، %E، %F، %f، %I، %l، %m، %p، %R، %S، %t، %x و %X می‌توانند بلافاصله پس از نویسهٔ % پرچم‌های اختیاری داشته باشند.

0

مقدار باید با صفر پر شود (zero-padded). این مورد برای پارامترهای %A، %E، %d، %F، %f، %l، %m، %S، %X و %x اعمال می‌شود. برای سایر پارامترها نادیده گرفته خواهد شد. اگر به همراه پرچم - استفاده شود، پرچم 0 نادیده گرفته خواهد شد.

-

مقدار نسبت به عرض فیلد، چپ‌چین شده و با نویسه‌های خالی (فاصله‌ها) پر خواهد شد. حالت پیش‌فرض راست‌چین است، که با 0 یا با فاصله پر می‌شود.

برخی از پارامترهای مربوط به MQTT را می‌توان با گزینه‌ای برای تعیین عرض فیلد آن‌ها به شیوه‌ای مشابه با قالب‌های معمول سبک printf قالب‌بندی کرد، یعنی این گزینه حداقل عرض را هنگام چاپ این پارامتر تعیین می‌کند. اگر طول خروجی کوچک‌تر از این عرض باشد، فیلد برای رسیدن به این عرض پر (pad) می‌شود. این مورد برای گزینه‌های %A، %C، %d، %E، %F، %f، %I، %l، %m، %p، %R، %S، %t، %x و %X اعمال می‌گردد.

برای مثال %10t حداقل عرض فیلد موضوع (topic) را روی ۱۰ نویسه تنظیم می‌کند.

برخی از پارامترهای مربوط به MQTT را می‌توان با گزینه‌ای برای تعیین حداکثر عرض فیلد به شیوه‌ای مشابه با قالب‌های معمول سبک printf قالب‌بندی کرد، برای مثال %.20t برای حداکثر عرض ۲۰. این مورد برای گزینه‌های %C، %I، %R و %t اعمال می‌شود.

برای مثال %10.10t حداقل عرض فیلد موضوع را روی ۱۰ نویسه و حداکثر عرض موضوع را روی ۱۰ نویسه تنظیم می‌کند، یعنی این فیلد همواره دقیقاً ۱۰ نویسه طول خواهد داشت.

پارامترهای %x و %X بار داده را به طور پیش‌فرض به عنوان یک رشتهٔ هگزادسیمال تکی خروجی می‌دهند. همچنین می‌توان بار دادهٔ هگزادسیمال را بر اساس طول انتخابی از نیم‌بایت‌ها (nibble) به فیلدهایی تقسیم کرد. برای مثال، %.2x بار داده را به مقادیر دو نیم‌بایتی یا یک‌بایتی، جداشده با فاصله، تقسیم می‌کند و ممکن است خروجی‌ای مانند 18 83 تولید کند.

نویسهٔ جداکننده به طور پیش‌فرض یک فاصله است، اما می‌توان با افزودن آن نویسه پس از عرض فیلد دودویی، آن را به یکی از !"#$&'()*+,-./:;<=>?@[\]^_`{|}~ تغییر داد. برای مثال %.2:x ممکن است خروجی‌ای مانند 18:83 تولید کند.

قالب خروجی تنها از استاندارد ممیز شناور IEEE 754 به همان صورتی که در پیوست F از ISO/IEC 9899:1999 شرح داده شده، پشتیبانی می‌کند. اگر سکوی منتشرکننده از استاندارد نمایش ممیز شناور دیگری به جز IEEE 754 استفاده می‌کند، سعی نکنید از %f یا %d استفاده کنید، چرا که داده‌های نامعتبر دریافت خواهید کرد. اگر مطمئن نیستید سکوی شما از چه نمایش ممیز شناوری استفاده می‌کند، به احتمال بسیار زیاد IEEE 754 است. اگر با مقادیر ناهنجار یا غیرمنتظره مواجه شدید، بررسی کنید که آیا عدد ممیز شناور در بار دادهٔ ارسال‌شده از سمت منتشرکننده در استاندارد IEEE 754 کدگذاری شده است یا خیر.

اگر می‌خواهید اعداد اعشاری شناور را چاپ کنید، مطمئن شوید که تنها در موضوعاتی مشترک می‌شوید که فقط اعداد اعشاری با قالب‌بندی IEEE 754 ارسال می‌کنند. پردازش در مورد اعداد اعشاری بسیار سخت‌گیرانه است و در صورت دریافت هر چیزی به جز ممیز شناور، یک پیام خطا چاپ خواهد شد.

•%% یک نویسهٔ واقعی %.
•%A ویژگی topic-alias در MQTT v5، در صورت وجود.
•%C ویژگی content-type در MQTT v5، در صورت وجود.
•%D ویژگی correlation-data در MQTT v5، در صورت وجود. توجه داشته باشید که این ویژگی به عنوان دادهٔ دودویی مشخص شده است، بنابراین ممکن است نویسه‌های غیرقابل‌چاپ تولید کند.
•%d بار داده به عنوان یک عدد ممیز شناور ۸ بایتی IEEE 754 (دوبل/double) در نظر گرفته می‌شود.
•%E ویژگی message-expiry-interval در MQTT v5، در صورت وجود.
•%F ویژگی payload-format-indicator در MQTT v5، در صورت وجود.
•%f بار داده به عنوان یک عدد ممیز شناور ۴ بایتی IEEE 754 در نظر گرفته می‌شود.
•%l طول بار داده به بایت.
•%m شناسهٔ پیام (تنها برای پیام‌های با QoS>0 مربوط است).
•%P ویژگی user-property در MQTT v5 در صورت وجود. این ویژگی در قالب key:value چاپ خواهد شد. ممکن است هر تعدادی از ویژگی‌های کاربر به یک پیام پیوست شده باشند و کلیدهای تکراری وجود داشته باشد.
•%p بایت‌های خام محموله (payload) (بسته به محموله ممکن است نویسه‌های غیرقابل‌چاپ تولید کند).
•%q سطح کیفیت خدمات (QoS) پیام.
•%R ویژگی response-topic در MQTT v5 در صورت وجود.
•%r پرچم نگه‌داشته‌شده (retained flag) برای پیام.
•%S ویژگی subscription-identifier در MQTT v5 در صورت وجود.
•%t موضوع (topic) پیام.
•%x محموله (payload) همراه با هر بایت به صورت یک عدد هگزادسیمال (حروف کوچک).
•%X محموله (payload) همراه با هر بایت به صورت یک عدد هگزادسیمال (حروف بزرگ).

•%I تاریخ و زمان در قالب ISO-8601، برای نمونه 2016-08-10T09:47:38+0100
•%j خروجی JSON از پارامترهای پیام و مهر زمانی (timestamp)، همراه با محموله‌ای داخل نقل‌قول و گریز داده شده (escaped). برای نمونه: {"tst":"2020-05-06T22:12:00.000000+0100","topic":"greeting","qos":0,"retain":0,"payload":"hello world"}
•%J خروجی JSON از پارامترهای پیام و مهر زمانی (timestamp)، همراه با محموله‌ای بدون علامت نقل‌قول و بدون گریز - بدین معنی که خود محموله باید JSON معتبر باشد. برای نمونه: {"tst":"2020-05-06T22:12:00.000000+0100","topic":"foo","qos":0,"retain":0,"payload":{"temperature":27.0,"humidity":57}}.

اگر محموله یک JSON معتبر نباشد، پیام خطای "Error: Message payload is not valid JSON on topic <topic>" در stderr چاپ خواهد شد.

•%U مهر زمانی یونیکس (Unix timestamp) با نانوثانیه، برای نمونه 1470818943.786368637
•@@ یک نویسه صریح @.
•@X نویسه نشان‌داده‌شده توسط X را به عنوان %X به تابع strftime ارسال می‌کند. گزینه‌های پشتیبانی‌شده وابسته به پلتفرم هستند.
•@N تعداد نانوثانیه‌های سپری‌شده در ثانیه جاری، با تفکیک‌پذیری زمانی متغیر بسته به پلتفرم.

•\\ یک نویسه صریح \.
•\0 یک نویسه پوچ (null). می‌تواند برای جداسازی پارامترهای مختلفی که ممکن است حاوی فاصله باشند (مانند topic، payload) استفاده شود تا پردازش با ابزارهایی مانند xargs(1) ساده‌تر گردد.
•\a هشدار/زنگ (alert/bell).
•\e توالی گریز، که برای نمونه می‌تواند همراه با کدهای رنگی ANSI برای ارائه خروجی رنگی استفاده شود.
•\n پایان خط (newline).
•\r بازگشت به ابتدای سطر (carriage return).
•\t تب افقی.
•\v تب عمودی.

کلاینت می‌تواند پیامی را نزد کارگزار (broker) ثبت کند که در صورت قطع ارتباط غیرمنتظره ارسال خواهد شد. برای اطلاعات بیشتر mqtt(7) را ببینید.

حداقل پیش‌نیاز برای این کار، استفاده از --will-topic جهت تعیین موضوعی (topic) است که وصیت باید روی آن ارسال شود. این کار منجر به ارسال پیامی بدون ماندگاری (non-retained)، با طول صفر و با QoS 0 می‌شود.

برای تغییر سایر پارامترهای وصیت از آرگومان‌های --will-retain، --will-payload و --will-qos استفاده کنید.

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

•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)

•user-property (جفت رشته UTF-8)

•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 موفقیت
•1 اتصال رد شد: نسخه پروتکل نامعتبر
•2 اتصال رد شد: شناسه پذیرفته نشد
•3 اتصال رد شد: سرور در دسترس نیست
•4 اتصال رد شد: نام کاربری/گذرواژه نادرست
•5 اتصال رد شد: غیرمجاز

کدهای CONNACK در MQTT v5:

•0 موفقیت
•128 خطای نامشخص
•129 بسته با ساختار نادرست
•130 خطای پروتکل
•131 خطای خاص پیاده‌سازی
•132 نسخهٔ پشتیبانی‌نشدهٔ پروتکل
•133 شناسهٔ کلاینت نامعتبر است
•134 نام کاربری یا گذرواژه نامعتبر است
•135 فاقد دسترسی (غیرمجاز)
•136 سرور در دسترس نیست
•137 سرور مشغول است
•138 مسدودشده
•139 سرور در حال خاموش شدن است
•140 روش احراز هویت نامعتبر است
•141 اتمام مهلت زنده نگه‌داشتن (Keep alive)
•142 نشست تصاحب شده است
•143 فیلتر موضوع نامعتبر است
•144 نام موضوع نامعتبر است
•147 فراتر رفتن از بیشینهٔ دریافت
•148 نام مستعار موضوع نامعتبر است
•149 بسته بیش از حد بزرگ است
•148 نرخ پیام بیش از حد بالا است
•151 سهمیه بیش از حد مجاز است
•152 اقدام مدیریتی
•153 قالب محموله (Payload) نامعتبر است
•154 ویژگی Retain پشتیبانی نمی‌شود
•155 سطح خدمات (QoS) پشتیبانی نمی‌شود
•156 از سرور دیگری استفاده کنید
•157 سرور منتقل شده است
•158 اشتراک‌های مشترک (Shared subscriptions) پشتیبانی نمی‌شوند
•159 نرخ اتصال بیش از حد مجاز است
•160 حداکثر زمان اتصال
•161 شناسه‌های اشتراک (Subscription IDs) پشتیبانی نمی‌شوند
•162 اشتراک‌های عام (Wildcard subscriptions) پشتیبانی نمی‌شوند

سایر کدها:

•27 مهلت زمانی در انتظار دریافت پیام به پایان رسید

$XDG_CONFIG_HOME/mosquitto_rr, $HOME/.config/mosquitto_rr, $HOME/snap/mosquitto/current/.config/mosquitto_rr (برای نصب‌های snap)

فایل پیکربندی برای گزینه‌های پیش‌فرض.

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

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

Roger Light <roger@atchoo.org>

04/03/2026 Mosquitto Project