'\" t .\" Title: mosquitto_ctrl .\" Author: [see the "Author" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 04/03/2026 .\" Manual: Commands .\" Source: Mosquitto Project .\" Language: English .\" .TH "MOSQUITTO_CTRL" "1" "04/03/2026" "Mosquitto Project" "Commands" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "نام (NAME)" mosquitto_ctrl_shell \- یک پوسته تعاملی برای پیکربندی نمونه کارگزار Mosquitto .SH "خلاصه دستور (SYNOPSIS)" .HP \w'\fBmosquitto_ctrl\fR\ 'u \fBmosquitto_ctrl\fR [\fB\-h\fR\ \fIhostname\fR] [\fB\-p\fR\ \fIport\-number\fR] [\fB\-u\fR\ \fIusername\fR] [\fB\-P\fR\ \fIpassword\fR] [\fB\-i\fR\ \fIclient\-id\fR] [\fB\-\-cafile\fR\ \fIfile\fR] [\fB\-\-capath\fR\ \fIdir\fR] [\fB\-\-cert\fR\ \fIfile\fR\ \fB\-\-key\fR\ \fIfile\fR] .SH "توضیحات (DESCRIPTION)" .PP \fBmosquitto_ctrl\fR ابزاری برای کمک به پیکربندی یک نمونه کارگزار Mosquitto است\&. .PP این صفحه راهنما نحوه استفاده از پوسته تعاملی را شرح می‌دهد\&. برای کسب اطلاعات درباره حالت صرفاً خط فرمانی، \fBmosquitto_ctrl\fR(1) را ببینید\&. پوسته تعاملی اکثر عملیات‌ها را بسیار ساده و مستقیم می‌سازد و برای سهولت استفاده توصیه می‌شود\&. .PP برای اجرا در حالت تعاملی، \fBmosquitto_ctrl\fR را بدون هیچ ماژول یا دستوری اجرا کنید؛ یعنی حداکثر همراه با مجموعه‌ای از گزینه‌هایی که در خلاصه دستور بالا توضیح داده شده است\&. پوسته شروع به کار خواهد کرد و یک اعلان (prompt) به شما نمایش داده می‌شود\&. .SH "اتصالات رمزنگاری‌شده (ENCRYPTED CONNECTIONS)" .PP \fBmosquitto_ctrl\fR از اتصالات رمزنگاری‌شده TLS پشتیبانی می‌کند\&. اکیداً توصیه می‌شود برای تمام موارد استفاده از راه دور از mosquitto_ctrl، از یک اتصال رمزنگاری‌شده استفاده کنید\&. .PP برای فعال‌سازی اتصالات TLS، با استفاده از شیوه‌نامه (scheme) \fBmqtts://\fR یا \fBwss://\fR در داخل پوسته متصل شوید، یا هنگام اجرای mosquitto_ctrl در خط فرمان از گزینه \fB\-\-cafile\fR یا \fB\-\-capath\fR استفاده کنید \- این کار همچنین اجازه می‌دهد از گواهی‌های سفارشی CA استفاده شود\&. .PP برای امنیت بیشتر می‌توان از گواهی‌های کلاینت نیز استفاده کرد\&. برای فعال‌سازی این مورد، از گزینه‌های \fB\-\-cert\fR و \fB\-\-key\fR استفاده نمایید\&. .SH "گردش کار نمونه در پوسته (EXAMPLE SHELL WORKFLOW)" .PP \fBمثال\ \&1.\ \&\fR .PP گردش کار معمول برای استفاده از پوسته تعاملی بدین صورت است که ابتدا احراز هویت را پیکربندی کرده و به یک کارگزار متصل شوید، سپس به حالت (mode) مورد نظر خود رفته و دستورهای آن را اجرا نمایید\&. به عنوان مثال، برای ایجاد یک گروه جدید در افزونه dynamic\-security: .sp .if n \{\ .RS 4 .\} .nf $ 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 .fi .if n \{\ .RE .\}.SH "رفتار پوسته (SHELL BEHAVIOUR)" .PP پوسته تعاملی در مجموعه‌ای از حالت‌های مختلف عمل می‌کند که هر کدام دستورهای متفاوتی در دسترس دارند\&. پوسته در صورت امکان از تکمیل خودکار با کلید تب (tab completion) برای دستورها و آرگومان‌های آن‌ها پشتیبانی می‌کند\&. معمولاً باید امکان‌پذیر باشد که با دو بار فشردن کلید تب، فهرستی از دستورها یا آرگومان‌های در دسترس فعلی نمایش داده شود\&. .PP پوسته دارای تاریخچه‌ای از دستورها است که با فشردن کلیدهای جهت‌نمای بالا و پایین قابل دسترسی است\&. این تاریخچه بر روی دیسک ذخیره نمی‌شود\&. .PP راهنمای هر دستور را می‌توان با وارد کردن \fBhelp\fR به همراه نام دستور به دست آورد\&. برای مثال: \fBhelp createGroup\fR\&. .PP حالت‌های مختلف عبارتند از: .PP \fBPre\-connection\fR .RS 4 در این حالت امکان تنظیم مشخصات احراز هویت، اتصال به یک broker، خواندن راهنما و خروج وجود دارد\&. .RE .PP \fBPost\-connection\fR .RS 4 در این حالت، mosquitto_ctrl به یک broker متصل است و می‌توانید بین ماژول‌های کنترلی مختلف جابه‌جا شوید، راهنما را مشاهده کنید یا خارج شوید\&. .RE .PP \fBdynsec\fR .RS 4 امکان ایجاد، حذف و ویرایش کاربران، گروه‌ها، نقش‌ها و ACLها را به شما می‌دهد\&. .RE .PP \fBbroker\fR .RS 4 امکان مشاهده اطلاعات listener و افزونه‌ها (plugins) را به شما می‌دهد\&. .RE .SH "احراز هویت (AUTHENTICATION)" .PP \fBmosquitto_ctrl\fR از احراز هویت با نام کاربری و گذرواژه، یا از طریق گواهی‌های کلاینت x509 پشتیبانی می‌کند\&. اگر از احراز هویت با نام کاربری و گذرواژه استفاده می‌کنید، باید پیش از اتصال، نام کاربری و گذرواژه را تنظیم کنید\&. این کار را می‌توان به یکی از دو روش انجام داد\&. روش نخست استفاده از گزینه‌های \fB\-u\fR و \fB\-P\fR در خط فرمان است\&. روش دوم استفاده از دستور \fBauth\fR در پوسته است\&. .PP احراز هویت در پوسته می‌تواند به یکی از دو روش انجام شود\&. روش نخست استفاده از دستور \fBauth\fR است که سپس نام کاربری و گذرواژه را درخواست می‌کند\&. روش دوم استفاده از دستور \fBauth\fR \fIusername\fR است که سپس گذرواژه را درخواست می‌کند\&. .SH "اتصال (CONNECTION)" .PP برای اتصال به یک broker، از دستور \fBconnect\fR استفاده کنید\&. .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} اتصال به broker در localhost روی پورت 1883\&. .sp .if n \{\ .RS 4 .\} .nf > connect .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} اتصال به یک broker مشخص با استفاده از پورت پیش‌فرض 1883\&. .sp .if n \{\ .RS 4 .\} .nf > connect mqtt://test\&.mosquitto\&.org .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} اتصال به یک broker مشخص با استفاده از پورت مشخص 1884\&. .sp .if n \{\ .RS 4 .\} .nf > connect mqtt://test\&.mosquitto\&.org:1884 .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} اتصال به یک broker مشخص با استفاده از TLS\&. .sp .if n \{\ .RS 4 .\} .nf > connect mqtts://test\&.mosquitto\&.org .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} اتصال به یک broker مشخص با استفاده از websockets\&. .sp .if n \{\ .RS 4 .\} .nf > connect ws://test\&.mosquitto\&.org .fi .if n \{\ .RE .\} .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} اتصال به یک broker مشخص با استفاده از websockets بر بستر TLS\&. .sp .if n \{\ .RS 4 .\} .nf > connect wss://test\&.mosquitto\&.org .fi .if n \{\ .RE .\} .RE.PP اگر گزینهٔ \fB\-h\fR در خط فرمان استفاده شود، پوسته بلافاصله تلاش می‌کند تا به میزبان مشخص‌شده متصل شود\&. .SH "حالت امنیت پویا (DYNAMIC\-SECURITY MODE)" .PP پس از اتصال، می‌توانید از دستور \fBdynsec\fR برای رفتن به حالت امنیت پویا استفاده کنید\&. این کار تنها در صورتی عمل خواهد کرد که کارگزار افزونهٔ dynamic\-security را بارگذاری کرده باشد و شما دسترسی لازم برای استفاده از آن را داشته باشید\&. .PP حالت امنیت پویا دستوراتی برای ایجاد، حذف و ویرایش کاربران، گروه‌ها، نقش‌ها و ACLها دارد\&. این دستورات را می‌توان با دو بار فشردن کلید Tab مشاهده کرد\&. برای دستورات مربوطه، نام‌های کاربری، نام‌های گروه و نام‌های نقش را می‌توان با فشردن کلید Tab به‌طور خودکار تکمیل کرد\&. راهنمای هر دستور با استفاده از \fBhelp\fR به همراه نام دستور در دسترس است\&. .PP برای خروج از حالت امنیت پویا، از دستور \fBreturn\fR استفاده کنید، یا دستور \fBexit\fR را برای خروج از پوسته به کار ببرید\&. .SH "حالت کارگزار (BROKER MODE)" .PP از دستور \fBbroker\fR برای تغییر وضعیت به حالت کارگزار استفاده کنید\&. این کار تنها در صورتی عمل خواهد کرد که گزینهٔ \fBenable_control_api\fR در کارگزار روی true تنظیم شده باشد\&. .PP حالت کارگزار شامل دستورهای \fBlistListeners\fR برای نمایش پیکربندی شنونده‌های فعال، و \fBlistPlugins\fR برای نمایش افزونه‌های بارگذاری‌شده کنونی است\&. .PP برای خروج از حالت کارگزار، از دستور \fBreturn\fR استفاده کنید، یا دستور \fBexit\fR را برای خروج از پوسته به کار ببرید\&. .SH "گزینه‌های اتصال (CONNECTION OPTIONS)" .PP گزینه‌های زیر می‌توانند در خط فرمان مشخص شوند: .PP \fB\-\-cafile\fR .RS 4 مسیر فایلی شامل گواهی‌های CA معتبر با کدگذاری PEM را مشخص می‌کند\&. برای فعال‌سازی ارتباط SSL به کار می‌رود\&. .sp همچنین ببینید: \fB\-\-capath\fR .RE .PP \fB\-\-capath\fR .RS 4 مسیر پوشه‌ای حاوی گواهی‌های CA معتبر با کدگذاری PEM را مشخص می‌کند\&. برای فعال‌سازی ارتباط SSL به کار می‌رود\&. .sp برای این که \fB\-\-capath\fR به‌درستی کار کند، فایل‌های گواهی باید پسوند «\&.crt» داشته باشند و باید با هر بار اضافه یا حذف کردن یک گواهی، دستور «openssl rehash » را اجرا کنید\&. .sp همچنین ببینید: \fB\-\-cafile\fR .RE .PP \fB\-\-cert\fR .RS 4 در صورتی که کارساز نیاز داشته باشد، مسیر یک فایل حاوی گواهی با کدگذاری PEM را برای این کلاینت مشخص می‌کند\&. .sp همچنین ببینید: \fB\-\-key\fR و بخش Encrypted Connections\&. .RE .PP \fB\-\-ciphers\fR .RS 4 فهرستی سازگار با openssl از رمزهای TLS جهت پشتیبانی در کلاینت\&. برای اطلاعات بیشتر \fBciphers\fR(1) را ببینید\&. .RE .PP \fB\-\-help\fR .RS 4 نمایش اطلاعات نحوه استفاده\&. .RE .PP \fB\-h\fR, \fB\-\-host\fR .RS 4 میزبان مورد نظر برای اتصال را مشخص می‌کند\&. پیش‌فرض localhost است\&. .RE .PP \fB\-i\fR, \fB\-\-id\fR .RS 4 شناسهٔ مورد استفاده برای این کلاینت\&. در صورت تعیین نشدن، یک شناسهٔ کلاینت بر اساس نسخهٔ MQTT مورد استفاده تولید خواهد شد\&. برای نسخه‌های v3\&.1\&.1/v3\&.1، کلاینت شناسه‌ای با قالب \fBmosq\-XXXXXXXXXXXXXXXXXX\fR ایجاد می‌کند که در آن \fBX\fRها با نویسه‌های حرفی\-عددی تصادفی جایگزین می‌شوند\&. برای نسخهٔ v5\&.0، کلاینت شناسه‌ای با طول صفر می‌فرستد و کارساز شناسه‌ای برای کلاینت تولید خواهد کرد\&. .RE .PP \fB\-\-key\fR .RS 4 مسیر فایلی شامل یک کلید خصوصی با کدگذاری PEM را برای این کلاینت جهت برقراری TLS دوطرفه با کارساز مشخص می‌کند\&. .sp همچنین ببینید: \fB\-\-cert\fR و بخش Encrypted Connections\&. .RE .PP \fB\-p\fR, \fB\-\-port\fR .RS 4 به درگاه مشخص‌شده متصل می‌شود\&. در صورت تعیین نشدن، مقدار پیش‌فرض 1883 برای MQTT معمولی یا 8883 برای MQTT بر بستر TLS استفاده خواهد شد\&. .RE .PP \fB\-u\fR, \fB\-\-username\fR .RS 4 یک نام کاربری برای احراز هویت در کارگزار تعیین می‌کند\&. .sp همچنین آرگومان \fB\-\-pw\fR را ببینید\&. .RE.SH "وضعیت خروج (EXIT STATUS)" .PP mosquitto_ctrl در صورت موفقیت صفر، یا در صورت بروز خطا مقداری غیرصفر بازمی‌گرداند\&. .SH "گزارش باگ‌ها (BUGS)" .PP اطلاعات مربوط به باگ‌های \fBmosquitto\fR را می‌توان در نشانی زیر یافت: \m[blue]\fB\%https://github.com/eclipse-mosquitto/mosquitto/issues\fR\m[] .SH "همچنین ببینید (SEE ALSO)" \fBmosquitto\fR(7), \fBmqtt\fR(7), \fBmosquitto_ctrl\fR(1), \fBmosquitto_rr\fR(1), \fBmosquitto_pub\fR(1), \fBmosquitto_sub\fR(1), \fBmosquitto\fR(8), \fBlibmosquitto\fR(3), \fBmosquitto-tls\fR(7) .SH "نویسندگان (AUTHORS)" .PP Roger Light