Menu Search Expand

Connect #


The Connect command creates a client and connects it to the specified broker. The client will stay connected until it is disconnected by the broker or the Disconnect method is called. To list all of the connected clients use the List method.

Simple Examples #

CommandExplanation
mqtt> conCreates and connect a new MQTT client with the default settings
mqtt> con -V 3 -h myHostCreates and connects an MQTT 3.1.1 client at myHost with the default port
mqtt> con -i mqtt-client -p 1884Creates and connects an MQTT client at localhost with port 1884 which is identified by mqtt-client.

Synopsis #

mqtt> con   [-h <host>] 
            [-p <port>]
            [-V <version>] 
            [-i <identifier>] 
            [-ip <identifierPrefix>]             
            [-cdsv]
            [-k <keepAlive>] 
            [-se <sessionExpiryInterval>] 
            [-up <connectUserProperties>]...
            [-ws]
            [-ws:path <webSocketPath>]
            [-u <user>] 
            [-pw [<password>]]
            [-pw:env [<environmentVariable>]]
            [-pw:file FILE]           
            [--cert <clientCertificate>] 
            [--key <clientPrivateKey>] 
            [--cafile FILE]... 
            [--capath DIR]...
            [--ciphers <cipherSuites>[:<cipherSuites>...]]... 
            [--tls-version <supportedTLSVersions>]... 
            [-Wd <willDelayInterval>]
            [-We <willMessageExpiryInterval>] 
            [-Wm <willMessage>] 
            [-Wq <willQos>] 
            [-Wr] 
            [-Wt <willTopic>]                                                        
            [-Wcd <willCorrelationData>] 
            [-Wct <willContentType>] 
            [-Wpf <willPayloadFormatIndicator>]
            [-Wrt <willResponseTopic>] 
            [-Wup <willUserProperties>]...
            [--rcvMax <receiveMaximum>]
            [--sendMax <sendMaximum>] 
            [--maxPacketSize <maximumPacketSize>] 
            [--sendMaxPacketSize <sendMaximumPacketSize>]
            [--topicAliasMax <topicAliasMaximum>] 
            [--sendTopicAliasMax <sendTopicAliasMaximum>] 
            [--[no-]reqProblemInfo] 
            [--[no-]reqResponseInfo]                                                              
            [--help] 

Options #

OptionLong VersionExplanationDefault
-h--hostThe MQTT host.localhost
-p--portThe MQTT port.1883
-V--mqttVersionThe MQTT version can be set to 3 or 5.MQTT v.5.0
-i--identifierA unique client identifier can be defined.A randomly defined UTF-8 String will be generated.
-ip--identifierPrefixThe prefix identifier which will prepend the randomly generated client name if no identifier is given.mqttClient
-d--debugPrint info level debug messages to the console.False
-v--verbosePrint detailed debug level messages to the console.False
-c--[no-]cleanStartEnable clean start if set.True
k--keepAliveThe keep alive of the client (in seconds)60
-se--sessionExpiryIntervalSession expiry value in seconds.0 (Instant Expiry)
-up--userPropertyA user property of the connect message. 
--ws Use WebSocket transport protocol.False
--ws:path The path to the WebSocket located at given broker host. 

Security Options #

OptionLong VersionExplanationDefault
-s--secureUse the default SSL configuration.False
-u--userA username for authentication can be defined. 
-pw--passwordA password for authentication can be defined directly.
If left blank the user will be prompted for the password in console.
 
-pw:env Define that the password for authentication is read in from an environment variable.MQTT_CLI_PW if option is specified without value
-pw:file Define the path to a file from which the password is read in. 
 --certThe path to the client certificate to use for client-side authentication. 
 --keyThe path to the client certificate corresponding private key to use for client-side authentication. 
 --cafilePath to a file containing a trusted CA certificate to enable encrypted certificate based communication. 
 --capathPath to a directory containing trusted CA certificates to enable encrypted certificate based communication. 
 --ciphersThe supported cipher suites in IANA string format concatenated by the ‘:’ character if more than one cipher should be supported.
e.g TLS_CIPHER_1:TLS_CIPHER_2
See https://www.iana.org/assignments/tls-parameters/tls-parameters.xml for supported cipher suite strings.
 
 --tls-versionThe TLS version to use - TLSv1.1 TLSv1.2 TLSv1.3TLSv1.2

Will Options #

OptionLong VersionExplanationDefault
-Wd--willDelayIntervalWill delay interval in seconds.0
-We--willMessageExpiryIntervalLifetime of the will message in seconds.
Can be disabled by setting it to 4_294_967_295
4_294_967_295 (Disabled)
-Wm--willPayloadPayload of the will message. 
-Wq--willQualityOfServiceQoS level of the will message.0
-Wr--[no-]willRetainRetain the will message.False
-Wt--willTopicTopic of the will message. 
-Wcd--willCorrelationDataCorrelation data of the will message 
-Wct--willContentTypeDescription of the will message’s content. 
-Wpf--willPayloadFormatIndicatorPayload format can be explicitly specified as UTF8 else it may be UNSPECIFIED. 
-Wrt--willResponseTopicTopic Name for a response message. 
-Wup--willUserPropertyA user property of the will message. 

Connect Restrictions #

OptionLong VersionExplanationDefault
 --rcvMaxThe maximum amount of not acknowledged publishes with QoS 1 or 2 the client accepts from the server concurrently.65535
 --sendMaxThe maximum amount of not acknowledged publishes with QoS 1 or 2 the client send to the server concurrently.65535
 --maxPacketSizeThe maximum packet size the client accepts from the server.268435460
 --sendMaxPacketSizeThe maximum packet size the client sends to the server.268435460
 --topicAliasMaxThe maximum amount of topic aliases the client accepts from the server.0
 --sendTopicAliasMaxThe maximum amount of topic aliases the client sends to the server.16
 --[no-]reqProblemInfoThe client requests problem information from the server.true
 --[no-]reqResponseInfoThe client requests response information from the server.false

Examples #

Connect a client to myHost on port 1884

mqtt> con -h myHost -p 1884

Connect a client to the default host on default port using authentication

mqtt> con -u username -pw password
# Or omit the password to get it prompted
mqtt> con -u username -P
Enter value for --password (The password for the client UTF-8 String.):

Connect a client with default settings and use it to publish

mqtt> con -i myClient
myClient@localhost> pub -t test -m "Hello World"

Connect a client with a will message

mqtt> con -wt willtopic -wq 2 -wm "Client disconnected ungracefully"

Connect a client with SSL using client side and server side authentication with a password encrypted private key

mqtt> con --cafile pathToServerCertificate.pem --tls-version TLSv.1.3
         --cert pathToClientCertificate.pem --key pathToClientKey.pem
Enter private key password:

Connect a client which is identified by myClient and disconnect it afterwards using default settings

mqtt> con -i myClient
myClient@localhost> dis
mqtt>

Connect a client which is identified by myClient on specific settings and disconnect it afterwards

mqtt> con -i myClient -h broker.hivemq.com -V 3
myClient@localhost> exit  # client is still connected
mqtt> dis -i myClient -h broker.hivemq.com

NOTE: Besides the identifier also hostname has to be given to uniquely identify the client. If you don’t specify these the default settings for these attributes will be used which may lead to unexpected behavior.