mosquitto_pub

Publish a temperature value of 32 on the topic sensors/temperature to 192.168.1.1 (defaults to localhost) with Quality of Service (QoS) set to 1

$ mosquitto_pub [[-h|--host]] [192.168.1.1] [[-t|--topic]] [sensors/temperature] [[-m|--message]] [32] [[-q|--qos]] [1]

$ mosquitto_pub [[-h|--host]] [192.168.1.1] [[-p|--port]] [1885] [[-t|--topic]] [sensors/temperature] [[-m|--message]] "[1266193804 32]"

$ mosquitto_pub [[-r|--retain]] [[-h|--host]] "[iot.eclipse.org]" [[-t|--topic]] [switches/kitchen_lights/status] [[-m|--message]] "[on]"

$ mosquitto_pub [[-t|--topic]] [sensors/temperature] [[-f|--file]] [data.txt]

$ mosquitto_pub [[-t|--topic]] [sensors/temperature] [[-s|--stdin-file]] < [data.txt]

$ [echo data.txt] | mosquitto_pub [[-t|--topic]] [sensors/temperature] [[-l|--stdin-line]]

mosquitto_pub [OPTIONS]
-t <topic>
[-m <message> | -f <file> | -l | -n]
[-h <host>]
[-p <port>]

-h, --host <host>
    Specify the hostname or IP address of the MQTT broker to connect to. Defaults to 'localhost'.

-p, --port <port>
    Define the port number for the broker connection. Defaults to 1883 for plain MQTT or 8883 for MQTT over TLS.

-t, --topic <topic>
    Required. The MQTT topic to which the message will be published.

-m, --message <message>
    The payload of the message to be published. Cannot be used with -f, -l, or -n.

-f, --file <file>
    Read the message payload from the specified file. Cannot be used with -m, -l, or -n.

-l, --stdin-line
    Read messages line by line from standard input, publishing each line as a separate message. Cannot be used with -m, -f, or -n.

-n, --null-message
    Publish a null (zero length) message. Cannot be used with -m, -f, or -l.

-q, --qos <qos>
    Set the Quality of Service level for the message (0, 1, or 2).

-r, --retain
    Mark the published message as a retained message. The broker will store it and send it to new subscribers to the topic.

-i, --id <id>
    Specify the client ID to use for the connection. If not provided, a default ID based on the process ID is used.

-u, --username <username>
    Provide a username for authentication with the broker.

-P, --pw <password>
    Provide a password for authentication with the broker. Used in conjunction with -u.

-k, --keepalive <seconds>
    Define the keepalive interval in seconds. The client will send a ping message if no other messages are exchanged within this period.

--will-topic <topic>
    Set the topic for the client's Last Will and Testament message. This message is published by the broker if the client disconnects unexpectedly.

--will-payload <payload>
    Set the payload for the Last Will and Testament message.

--will-qos <qos>
    Set the Quality of Service level for the Last Will and Testament message.

--will-retain
    Set the retain flag for the Last Will and Testament message.

--cafile <file>
    Path to a file containing trusted CA certificates for TLS/SSL connection.

--capath <directory>
    Path to a directory containing trusted CA certificates for TLS/SSL connection.

--cert <file>
    Path to the client certificate file for client authentication (mutual TLS).

--key <file>
    Path to the client private key file for client authentication.

--tls-version <version>
    Specify the TLS protocol version to use (e.g., tlsv1.2, tlsv1.3).

--ciphers <ciphers>
    Specify the permitted TLS cipher suites.

--insecure
    Allow connection to brokers using self-signed certificates without validation. Not recommended for production.

--proxy <address>
    Connect to the MQTT broker via a SOCKS5 proxy.

--reconnect-delay <seconds>
    Set the initial delay in seconds before attempting to reconnect to the broker after a disconnection.

--reconnect-max-delay <seconds>
    Set the maximum delay in seconds between reconnect attempts. Used with --reconnect-delay for exponential backoff.

-d, --debug
    Enable debug messages for detailed client operation insights.

-V, --version
    Display the version information of the mosquitto_pub client.

--help
    Show the help message and exit.

mosquitto_pub is a command-line client used to publish messages to an MQTT broker. It provides a straightforward way to send data to specific topics on an MQTT server, enabling communication with various IoT devices and applications. This tool is essential for testing MQTT setups, scripting automated data sends, or integrating with sensor networks. It fully supports standard MQTT features, including Quality of Service (QoS) levels, retained messages, and Last Will and Testament functionalities. Furthermore, it offers robust security options such as TLS/SSL encryption and username/password authentication, making it adaptable for both secure and insecure MQTT deployments.

Network Connectivity: Ensure the MQTT broker is running and accessible on the specified host and port. Firewall rules can block connections.
Security: Using -u and -P sends credentials in plain text over non-TLS connections. Always use TLS/SSL (--cafile, --cert, --key) for production environments to protect sensitive information.
Message Size: Extremely large messages might exceed broker limits or network buffer constraints, leading to transmission failures.
Topic Structure: While publishing, ensure the topic string adheres to MQTT standards (e.g., no leading/trailing slashes if not intended as root, avoid wildcards for direct publishing).

Messages published via mosquitto_pub consist of two primary components: a payload (the actual data being sent) and a topic (a hierarchical string that acts as a routing key). The topic is crucial for subscribers to filter and receive messages they are interested in. The payload can be any arbitrary binary data, though it commonly contains text formats like JSON, XML, or plain text, or binary sensor readings.

MQTT defines three levels of Quality of Service to ensure message delivery reliability:
QoS 0 (At Most Once): Messages are delivered once, with no confirmation. This is the fastest option, but messages may be lost if the network fails or the broker is unavailable.
QoS 1 (At Least Once): Messages are delivered at least once. The publisher receives confirmation (PUBACK) that the message reached the broker, but duplicates are possible.
QoS 2 (Exactly Once): Messages are delivered exactly once. This is the slowest but most reliable option, guaranteeing no message loss and no duplication.

The Mosquitto project, which includes the mosquitto_pub utility, was initiated by Roger Light as an open-source implementation of an MQTT broker. It has gained widespread adoption in IoT and M2M communication due to its lightweight nature, efficiency, and strict adherence to the MQTT protocol specification. mosquitto_pub, alongside its counterpart mosquitto_sub, serves as a fundamental command-line tool for interacting with any MQTT broker, proving invaluable for development, testing, and scripting in MQTT-based systems. Its ongoing development closely mirrors the evolution and releases of the MQTT protocol itself.

mosquitto_sub(1), mosquitto(8), mosquitto_passwd(1)