| MOSQUITTO_PUB(1) | Commands | MOSQUITTO_PUB(1) |
نام (NAME)
mosquitto_pub - کلاینت انتشار پیام‌های ساده در پروتکل MQTT نسخه‌های ۵، ۳.۱.۱ و ۳.۱
خلاصه دستور (SYNOPSIS)
mosquitto_pub [options] -t topic {payload-options}
options:
[auth-options] [connection-options] [misc-options] [mqtt-options]
[output-options] [publish-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:
[-o config-file]
mqtt-options:
[-c]
[-D command identifier value]
[-i client-id]
[-I client-id-prefix]
[-k keepalive-time]
[-x session-expiry-interval]
[-V protocol-version]
[--will-topic topic [--will-payload payload] [--will-qos qos] [--will-retain]]
output-options:
[-d] [--quiet]
payload-options:
-f file | -l | -m message |
-n | -s
publish-options:
[-q message-QoS] [-r]
[--repeat count]
[--repeat-delay seconds]
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_pub [--help]
توضیحات (DESCRIPTION)
mosquitto_pub یک کلاینت ساده برای پروتکل MQTT نسخه ۵، ۳.۱.۱ و ۳.۱ است که یک پیام منفرد را بر روی یک موضوع (topic) منتشر کرده و سپس خارج می‌شود.
اتصالات رمزنگاری‌شده (ENCRYPTED CONNECTIONS)
این کلاینت از اتصالات رمزنگاری‌شده با TLS پشتیبانی می‌کند. اکیداً توصیه می‌شود برای هرگونه کاربردی فراتر از ساده‌ترین تنظیمات آزمایشی، از اتصال رمزنگاری‌شده استفاده کنید.
جهت فعال‌سازی اتصالات TLS هنگام استفاده از گواهی‌های x509، می‌توان یکی از گزینه‌های --cafile یا --capath را مشخص کرد.
همچنین اگر از گزینه -p 8883 استفاده شود، گواهی‌های ارائه‌شده توسط سیستم‌عامل بارگذاری خواهند شد و نیازی به مشخص کردن هیچ‌یک از گزینه‌های --cafile یا --capath نخواهد بود.
برای فعال‌سازی اتصالات TLS در صورت استفاده از TLS-PSK، باید از گزینه‌های --psk و --psk-identity استفاده کنید.
گزینه‌ها (OPTIONS)
سه روش برای ارائه گزینه‌ها به mosquitto_pub وجود دارد: فایل پیکربندی پیش‌فرض، یک فایل پیکربندی مشخص‌شده، یا گزینه‌ها در خط فرمان.
فایل پیکربندی پیش‌فرض (Default Config File)
فایل پیکربندی پیش‌فرض در مسیر $XDG_CONFIG_HOME/mosquitto_pub یا $HOME/.config/mosquitto_pub در سیستم‌های سازگار با POSIX، یا در مسیر %USERPROFILE%\mosquitto_pub در سیستم‌های ویندوز قرار دارد.
محتوای فایل پیکربندی باید شامل گزینه‌ها باشد، هر گزینه در یک خط به صورت: -option value. اگر گزینه‌ها در خط فرمان نیز مشخص شوند، آن گزینه‌ها مقادیر تعیین‌شده در فایل پیکربندی را بازنویسی خواهند کرد. استثنای این قاعده گزینه‌های نوع پیام هستند که تنها یکی از آن‌ها می‌تواند مشخص شود. همچنین توجه داشته باشید که در حال حاضر برخی گزینه‌ها را نمی‌توان نفی کرد، مانند -S. گزینه‌های رمزنگاری TLS را می‌توان با گزینه --no-tls غیرفعال کرد.
خطوطی از فایل پیکربندی که با نویسه # شروع می‌شوند به عنوان توضیحات در نظر گرفته شده و پردازش نمی‌شوند.
پیشنهاد می‌شود فایل‌های پیکربندی عمدتاً برای احراز هویت به کار روند. استفاده از فایل پیکربندی امکان احراز هویت را بدون نیاز به نمایش نام کاربری و گذرواژه در خط فرمان فراهم می‌کند.
فایل پیکربندی (Config File)
از نسخه ۲.۱ در دسترس است.
یک فایل پیکربندی را می‌توان با گزینه -o config-file در خط فرمان مشخص کرد. در صورت استفاده از گزینه -o فایل پیکربندی پیش‌فرض بارگذاری نخواهد شد.
قالب آن همانند فایل پیکربندی پیش‌فرض است.
فهرست گزینه‌ها (The options)
-A
-c, --disable-clean-session
هنگامی که یک نشست روی کارگزار پایدار بماند، اشتراک‌های کلاینت پس از قطع اتصال حفظ می‌شوند و پیام‌های بعدی با سطوح کیفیتی QoS 1 و QoS 2 که برسند ذخیره می‌گردند. زمانی که کلاینت دوباره متصل شود و نشست را پاک نکند، تمامی پیام‌های صف‌بندی‌شده را دریافت خواهد کرد.
در صورت استفاده از این گزینه، شناسه کلاینت باید به صورت دستی با --id تنظیم شود.
--cafile
همچنین ببینید: --capath
--capath
برای کارکرد صحیح --capath باید پسوند فایل‌های گواهی «.crt» باشد و هر بار که گواهی جدیدی اضافه یا حذف می‌کنید، دستور «openssl rehash <path to capath>» را اجرا نمایید.
همچنین ببینید: --cafile
--cert
همچنین ببینید: --key و بخش «اتصالات رمزنگاری‌شده».
--ciphers
-d, --debug
-D, --property
-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 رشته دوم جفت خواهد بود.
-f, --file
--help
-h, --host
-i, --id
-I, --id-prefix
--insecure
-k, --keepalive
--key
همچنین ببینید: --cert و بخش «اتصالات رمزنگاری‌شده».
--keyform
همچنین ببینید: --tls-engine.
-L, --url
بسته به طرح نشانی (scheme)، پورت پیش‌فرض مقادیر متفاوتی خواهد داشت: mqtt:// - 1883، mqtts:// - 8883، ws:// - 80، wss:// - 443.
-l, --stdin-line
-m, --message
-n, --null-message
--nodelay
--no-tls
غیرفعال‌سازی کامل استفاده از رمزنگاری TLS. این گزینه زمانی کاربرد دارد که گزینه‌های TLS را در یک فایل پیکربندی تعیین کرده‌اید اما قصد دارید آن گزینه‌ها را موقتاً غیرفعال کنید. همچنین استفاده خودکار از TLS را هنگام اتصال به پورت 8883 متوقف می‌سازد.
-o config-file
بارگذاری گزینه‌ها از یک فایل پیکربندی. بخش‌های «فایل پیکربندی پیش‌فرض» و «فایل پیکربندی» در ابتدای بخش گزینه‌ها را مشاهده کنید.
-p, --port
-P, --pw
همچنین گزینه --username را مشاهده کنید.
--proxy
اگر نام کاربری داده نشود، هیچ تلاشی برای احراز هویت انجام نمی‌شود. اگر پورت داده نشود، مقدار پیش‌فرض ۱۰۸۰ استفاده می‌شود.
اگر میزبان به صورت نشانی IPv6 داده شود، باید درون کروشه قرار گیرد؛ مانند socks5h://[::1]:1080. توجه داشته باشید که کروشه‌ها در برخی پوسته‌ها معنی خاصی دارند، بنابراین ممکن است لازم باشد نشانی پروکسی داخل نقل‌قول تکی یا دوتایی قرار گیرد.
نسخه‌های بیشتری از SOCKS ممکن است در آینده بسته به نیاز اضافه شوند و از پیشوندهای پروتکل متفاوتی استفاده کنند، همان‌طور که در curl(1) توضیح داده شده است.
--psk
--psk-identity
-q, --qos
--quiet
-r, --retain
--repeat
همچنین ببینید: --repeat-delay.
--repeat-delay
توجه داشته باشید که هیچ تضمینی برای فاصله زمانی دقیق بین پیام‌ها وجود ندارد؛ این گزینه صرفاً حداقل زمان از تحویل یک پیام تا شروع انتشار پیام بعدی را تعریف می‌کند.
-s, --stdin-file
-S
-t, --topic
--tls-alpn
--tls-engine
همچنین ببینید: --keyform.
--tls-engine-kpass-sha1
همچنین ببینید: --tls-engine.
--tls-keylog file
ثبت گزارش اطلاعات اتصال TLS در file. این گزینه به ابزارهایی مانند tcpdump، wireshark و mqttshark امکان رمزگشایی ترافیک TLS و بررسی ترافیک MQTT را می‌دهد. در Wireshark این کار با تنظیم گزینه (Pre)-Master-Secret log filename برای پروتکل Transport Layer Security قابل انجام است.
این گزینه فقط باید برای اشکال‌زدایی استفاده شود و هرگز نباید در محیط عملیاتی به کار رود.
--tls-use-os-certs
--tls-version
-u, --username
همچنین آرگومان --pw را مشاهده کنید.
--unix
برای پیکربندی Mosquitto جهت گوش دادن روی سوکت یونیکس، گزینه socket_domain در mosquitto.conf(5) را بررسی کنید.
-V, --protocol-version
--will-payload
--will-qos
--will-retain
--will-topic
--ws
-x
اگر نشست با استفاده از -x یا -c طوری تنظیم شود که هرگز منقضی نشود، باید شناسه کلاینت مشخص گردد.
وصیت‌نامه‌ها (WILLS)
کلاینت می‌تواند پیامی را نزد کارگزار ثبت کند تا در صورت قطع اتصال غیرمنتظره، به صورت خودکار ارسال شود. برای اطلاعات بیشتر به mqtt(7) مراجعه کنید.
حداقل نیاز برای این ویژگی، استفاده از --will-topic جهت تعیین موضوعی است که پیام وصیت باید روی آن ارسال شود. این کار منجر به ارسال پیامی با طول صفر، بدون نگهداری (non-retained) و با سطح QoS 0 خواهد شد.
از آرگومان‌های --will-retain، --will-payload و --will-qos برای تغییر سایر پارامترهای وصیت استفاده کنید.
ویژگی‌ها (PROPERTIES)
گزینه -D / --property امکان افزودن ویژگی‌ها را در مراحل مختلف اجرای mosquitto_pub فراهم می‌کند. ویژگی‌های پشتیبانی‌شده برای هر دستور به شرح زیر است:
اتصال (Connect)
انتشار (Publish)
قطع اتصال (Disconnect)
ویژگی‌های وصیت (Will properties)
وضعیت خروج (EXIT STATUS)
در صورت موفقیت مقدار صفر و در صورت بروز خطا مقداری غیر صفر بازگردانده می‌شود. اگر اتصال توسط کارگزار در سطح MQTT رد شود، کد خروج همان کد دلیل CONNACK خواهد بود. در صورت بروز هر خطای دیگری، کد خروج مقدار بازگشتی libmosquitto است.
کدهای CONNACK در MQTT نسخه v3.1.1:
کدهای CONNACK در MQTT نسخه v5:
سایر کدها:
مثال‌ها (EXAMPLES)
انتشار اطلاعات دما بر روی میزبان محلی (localhost) با سطح کیفیت خدمات QoS 1:
انتشار برچسب زمان و اطلاعات دما به یک میزبان راه دور بر روی پورت غیر استاندارد و با QoS 0:
انتشار وضعیت کلید روشنایی. پیام به صورت نگهداری‌شده (retained) تنظیم می‌شود زیرا ممکن است فاصله زمانی زیادی میان رویدادهای تغییر وضعیت کلید وجود داشته باشد:
ارسال محتوای یک فایل به دو روش:
ارسال داده‌های تحلیل‌شده مصرف برق از یک کنتور Current Cost، با خواندن از ورودی استاندارد (stdin) به طوری که هر خط به عنوان یک پیام جداگانه ارسال شود:
روشن کردن یک وسیله برقی با استفاده از zigbee2mqtt و یک پریز هوشمند با پیکربندی مناسب:
فایل‌ها (FILES)
$XDG_CONFIG_HOME/mosquitto_pub, $HOME/.config/mosquitto_pub, $HOME/snap/mosquitto/current/.config/mosquitto_pub (برای نسخه‌های نصب‌شده از طریق snap)
اشکالات (BUGS)
اطلاعات مربوط به اشکالات mosquitto را می‌توانید در نشانی زیر بیابید: https://github.com/eclipse-mosquitto/mosquitto/issues
همچنین ببینید (SEE ALSO)
mosquitto(7), mqtt(7), mosquitto_rr(1), mosquitto_sub(1), mosquitto(8), libmosquitto(3), mosquitto-tls(7)
نویسنده (AUTHOR)
Roger Light <roger@atchoo.org>
| 04/03/2026 | Mosquitto Project |