Command - Run

Description and usage of the run command

Start the message broker and connect to a FoxMQ cluster.

Usage: foxmq run <--secret-key <SECRET_KEY>|--secret-key-file <SECRET_KEY_FILE>> [CONFIG_DIR]

Windows users: Traffic on the loopback interface (localhost/127.0.0.1) does not connect to applications listening on 0.0.0.0. Use 127.0.0.1 IP to listen for loopback connections.

Options listing

• --log, -l Set the format of log output.

  • Default: full

  • Options: full, compact, pretty, json

    • json is structured and is intended for usage by tools that process structured logs in production environments, and is not optimized for human readability.

  • Example: --log=json May lead to a message such as (note: JSON output is not prettiefied, this is just an example):

{
    "timestamp":"2024-04-12T23:14:00.243145Z",
    "level":"INFO",
    "fields":{
        "message":"listening for connections",
        "listen_addr":"0.0.0.0:1883"
    },
    "target":"foxmq::mqtt::broker"
}

• --mqtt-addr, -L The TCP socket address to listen for MQTT (non-TLS) connections from clients.

  • Default: 0.0.0.0:1883

• --cluster-addr, -C The UDP socket address to listen for cluster connections from other FoxMQ brokers.

  • Default: 0.0.0.0:19793

• --allow-anonymous-login

  Allow clients to authenticate without providing user credentials

  • Default: false (not present)

• --silent-connect-errors Don't respond to mqtt CONNECT packets if the result would be an error. This can be used to avoid advertising that an MQTT broker is running on the given port, which makes it harder to categorize in a port scanning attack and identify as a potential target. By default, a response is sent to the client detailing the reason why the handshake failed. When enabled, the error is simply logged at DEBUG level, and the socket is silently closed.

  • Default: false (not present)

• --secret-key, -k Read the P-256 secret key used to identify this broker in the cluster from hex encoded DER. If --tls-key-file is not provided and mqtts is enabled, this or --secret-key-file will be used by default.

  • env: SECRET_KEY=

  • Conflicts: --secret-key-file

• --secret-key-file, -f Read the PEM-encoded P-256 secret key used to identify this broker in the cluster from a file.

  • env: SECRET_KEY_FILE=

  • Conflicts: --secret-key

• --mqtts Enable listening for MQTT-over-TLS connections on a separate socket (0.0.0.0:8883 by default)

• --mqtts-addr The TCP socket address to listen for MQTT-over-TLS (mmqts) connections from clients.

  • Default: 0.0.0.0:8883

• --server-name The domain name to report for Server Name Identification (SNI) in TLS

  • Default: foxmq.local

• --tls-key-file Override the secret key used for TLS handshakes.

  • Default: The main secret key (--secret-key/seecret-key-file)

• --tls-cert-file Path to the X.509 certificate to use for TLS.

  • Default: A certificate self-signed with TLS key (--tls-key-file or the main key)

Example

Refer to Quick Start - Direct or Quick Start - Docker for more in-depth examples.

foxmq run \
    --log=full
    --mqtt-addr "0.0.0.0:1883" \
    --cluster-addr "0.0.0.0:19793"
    --secret-key-file foxmq.d/key_0.pem \
    --mqtts \
    --mqtts-addr "0.0.0.0:8883"
    --server-name "foxmq.local
    --tls-key-file foxmq.d/key_0.pem
    --tls-cert-file "my-cert.crt"