EMQXでcurlを使う

curlはデータ転送や自動化に広く使われているコマンドラインツールです。2020年以降、curlはMQTTプロトコルをサポートしており、curl 8.19.0（2026年3月予定）以降ではMQTTS（TLS上のMQTT）もサポートしています。

curlを使うことで、開発者は言語固有のMQTTクライアントSDKをインストールせずに、コマンドラインから直接EMQXに接続し、メッセージのパブリッシュやトピックのサブスクライブが可能です。これにより、手軽なテストやスクリプト作成、IoTプロトタイピングに便利な選択肢となります。

このページでは、curlを使ったEMQXとのMQTT/MQTTS通信の接続、パブリッシュ／サブスクライブ、認証、TLS設定、よくあるトラブルシューティングについて説明します。

curlのバージョン要件

機能	最低バージョン	リリース時期
MQTT (`mqtt://`)	7.70.0	2020年4月
MQTTS (`mqtts://`)	8.19.0	2026年3月初旬予定

インストールされているcurlのバージョンを確認するには：

bash

curl --version

Protocolsリストにmqtt（およびcurl ≥ 8.19.0の場合はmqtts）が含まれていることを確認してください。

curlのバージョンが古い場合は、パッケージマネージャーでアップグレードするか、https://curl.se/download から最新版をダウンロードしてください。
macOSではbrew install curlで最新バージョンをインストールできます。

MQTTブローカーのセットアップ

接続先としてMQTTブローカーが必要です。このガイドではMQTTとMQTTSの両方をサポートするEMQXを使用します。

EMQXパブリックブローカー（テスト用）

独自のブローカーを用意せずに手軽にテストしたい場合は、EMQXのパブリックブローカーを利用できます。

パラメーター	値
ブローカー	`broker.emqx.io`
MQTTポート	`1883`
MQTTSポート	`8883`

パブリックブローカーはテストおよびデモ目的のみの利用を想定しています。

EMQX Enterpriseのデプロイメント

本番環境では、curlを自分のEMQX Enterpriseデプロイメントに接続します。ブローカーのアドレス、ポート、認証情報、TLS設定は環境に応じて設定してください。

一般的な構成例：

カスタムのブローカーホスト名またはIPアドレス
EMQX Enterpriseで有効化されたMQTTおよび/またはMQTTSリスナー
ユーザー名／パスワード認証、トークン認証、相互TLS認証など
トピックに適用されるアクセス制御ルール（ACL）

curlコマンドを作成する際は、EMQX Enterpriseのリスナー設定、認証設定、TLS設定を参照してください。

注意

すべての例でbroker.emqx.ioを自分のEMQX Enterpriseブローカーのアドレスに置き換えてください。
接続前にEMQX Enterpriseで対応するMQTTまたはMQTTSリスナーが有効になっていることを確認してください。

自己管理型のEMQX Enterpriseのほか、完全マネージドMQTTサービスであるEMQX Cloud（サーバレスまたは専用）にもcurlで接続可能です。
curlのMQTT/MQTTS利用方法は同じです。EMQX Cloudから提供されるブローカーアドレス、ポート、認証情報を使用してください。

curlでEMQX Enterpriseに接続する

MQTTでは、クライアントはトピックのサブスクライブやメッセージのパブリッシュなどの操作の一環としてブローカーに接続を確立します。独立した「接続」コマンドはありません。

curlでEMQX Enterpriseを使う場合、サブスクライブやパブリッシュコマンドを実行すると、指定したEnterpriseブローカーアドレス（および認証やTLS設定があればそれら）を用いて自動的に接続が確立されます。

例えば、以下のコマンドはEMQX Enterpriseに接続し、トピックをサブスクライブします。

bash

curl -N mqtts://your-enterprise-broker.example.com/curl/test

注意：MQTTS（mqtts://）はcurl 8.19.0以降が必要です。curl 7.70.0〜8.18.xの場合はmqtt://を使用してください。

curlのMQTT URLスキームの理解

curlはMQTT操作にURLベースの構文を使用します：

mqtt[s]://[user:password@]broker[:port]/topic

各要素の意味：

mqtt[s]：プロトコル（mqttまたはmqtts）
[user:password@]：省略可能な認証情報
broker：ブローカーのホスト名またはIPアドレス
[:port]：省略可能なポート番号。指定しない場合はデフォルトを使用
- mqtt://は1883
- mqtts://は8883
/topic：MQTTトピックのパス（例：/sensor/temperature）

curlのMQTT出力フォーマット

トピックをサブスクライブすると、curlは以下の形式で生のMQTTメッセージデータを出力します：

[2バイト：トピック長（ビッグエンディアン）] [トピック文字列] [ペイロード]

例えば、トピックcurl/testにメッセージ"hello"が届くと、以下のように表示されます：

curl/testhello

この出力はトピック名とペイロードが連結されたバイナリ形式であり、パースしないと読みづらいです。

以下のMQTTメッセージのパース節で変換例を紹介します。

トピックのサブスクライブ

サブスクライブは接続を維持し、受信したメッセージをstdoutに出力します。

基本的なサブスクライブ（暗号化なし）

bash

curl -N mqtt://broker.emqx.io/curl/test --output messages.bin

-Nオプションは出力バッファリングを無効にし、メッセージを即時に表示します。

MQTTSによるセキュアサブスクライブ（curl ≥ 8.19.0）

bash

curl -N mqtts://broker.emqx.io/curl/test --output messages.bin

認証付きサブスクライブ

bash

curl -N -u "username:password" \
  mqtts://your-broker.emqxsl.com/curl/test --output messages.bin

MQTTメッセージのパース

curlのサブスクライブ出力はバイナリ形式であり、整形されたテキストではありません。

各メッセージは以下の構造です：

2バイト：トピック長（ビッグエンディアン）
トピック文字列
ペイロード（生データ）

そのため、出力はトピックとペイロードが連結された形で、人間には読みづらいです。

Bashのワンライナー例

サブスクライブ出力を読みやすくするには、curlの出力をシェルでパースします：

bash

curl -sN mqtt://broker.emqx.io/curl/test | \
  while IFS= read -r -d $'\0' d; do
    [ -z "$d" ] && continue

    # curlのMQTTサブスクライブ出力は2バイトのトピック長（MSB,LSB）、トピック、ペイロード。
    # このループはNUL(0x00)を区切り文字に使い、LSBを先に読み、MSB=0と仮定（トピック長0〜255に対応）。
    lsb=$(printf "%d" "'${d:0:1}")
    topic_len=$((lsb))
    echo "[${d:1:$topic_len}] ${d:$((1 + topic_len))}"
  done

出力例：

[curl/test] hello

このパーサーは簡易的な方法で、デモ用途に適しています。

動作概要：

ストリームをヌルバイトで分割
2バイトのトピック長の下位バイトを取得（上位バイトは0と仮定）
トピック文字列とペイロードを長さ指定で抽出
各メッセージを[トピック] ペイロード形式で表示

生データをファイルに保存して確認

MQTTメッセージのバイナリ構造を理解するために、生のサブスクライブ出力をファイルに保存し、手動で確認できます。

保存例：

bash

curl -sN mqtt://broker.emqx.io/curl/test > messages.bin

hexdumpで内容を確認：

bash

hexdump -C messages.bin

トピック長のプレフィックス、トピックバイト列、ペイロードのレイアウトが明確に見えます。

再利用可能なシェル関数

繰り返し使う場合は、パーサーをシェル関数にまとめられます：

bash

mqtt_subscribe() {
  curl -sN "$1" | while IFS= read -r -d $'\0' d; do
    [ -z "$d" ] && continue

    # curlのMQTTサブスクライブ出力は2バイトのトピック長（MSB,LSB）、トピック、ペイロード。
    # このループはNUL(0x00)を区切り文字に使い、LSBを先に読み、MSB=0と仮定（トピック長0〜255に対応）。
    lsb=$(printf "%d" "'${d:0:1}")
    topic_len=$((lsb))
    echo "[${d:1:$topic_len}] ${d:$((1 + topic_len))}"
  done
}

使用例：

bash

mqtt_subscribe "mqtt://broker.emqx.io/curl/test"

本番用途や複雑なパースが必要な場合は、MQTTX CLIの利用を検討してください。MQTT 5.0完全対応、QoS処理、ワイルドカードサブスクライブなどが可能で、整形済み出力を提供します。

メッセージのパブリッシュ

メッセージをパブリッシュするには、curlの-d（データ）オプションにペイロードを指定します。

基本的なパブリッシュ（暗号化なし）

bash

curl -d "Hello from curl" \
  mqtt://broker.emqx.io/curl/test

MQTTSによるセキュアパブリッシュ（curl ≥ 8.19.0）

bash

curl -d "Secure message from curl" \
  mqtts://broker.emqx.io/curl/test

JSONペイロードのパブリッシュ

bash

curl -d '{"sensor_id":"temp-001","value":23.5}' \
  mqtt://broker.emqx.io/sensors/temperature

認証付きパブリッシュ

bash

curl -u "username:password" \
  -d '{"status":"online"}' \
  mqtts://your-broker.example.com/devices/status

主要なcurlオプション

本ドキュメントで使用されるcurlコマンドラインオプションの概要：

オプション	説明	主な用途
`-N`	出力バッファリングを無効化（サブスクライブ時必須）	サブスクライブ
`-d`	パブリッシュするメッセージペイロード	パブリッシュ
`-u user:pass`	ユーザー名とパスワードによる認証	認証
`-v`	詳細出力（MQTTハンドシェイク表示）	トラブルシューティング
`-s`	サイレントモード（進捗表示抑制）	スクリプト
`--cacert`	TLS検証用のCA証明書	MQTTS
`--cert`	相互TLS用のクライアント証明書	MQTTS
`--key`	相互TLS用のクライアント秘密鍵	MQTTS
`-k`	TLS検証をスキップ（テスト用のみ推奨）	トラブルシューティング

curlの全オプション一覧は公式ドキュメントを参照してください。

TLS設定（MQTTS）

CA証明書による検証

bash

curl --cacert /path/to/ca.crt \
  -d "TLS verified message" \
  mqtts://your-broker.example.com/secure/topic

相互TLS（mTLS）

bash

curl --cacert /path/to/ca.crt \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  -d "mTLS message" \
  mqtts://your-broker.example.com/secure/topic

証明書検証をスキップする場合は-kを使用しますが、本番環境では推奨しません。

よくあるユースケース

ブローカー接続テスト

bash

curl -v mqtt://broker.emqx.io/curl/test

DNS解決、TCP接続、MQTTハンドシェイクの動作確認ができます。

接続成功の目安

詳細出力に以下が含まれます：

ブローカーのホスト名がIPアドレスに解決される
ポート1883（MQTT）または8883（MQTTS）へのTCP接続成功
MQTTハンドシェイクがエラーなく完了

エラーが表示されず正常終了すれば、EMQXブローカーへの接続が確立されています。

シェルスクリプトやIoTプロトタイピング

例：5秒ごとに温度センサーのデータをパブリッシュするシミュレーション

bash

#!/bin/bash
BROKER="mqtt://broker.emqx.io"
TOPIC="sensors/room1/temperature"

while true; do
  TEMP=$(awk -v min=20 -v max=30 'BEGIN{srand(); print min+rand()*(max-min)}')
  PAYLOAD="{\"temperature\": $TEMP, \"timestamp\": $(date +%s)}"
  curl -s -d "$PAYLOAD" "$BROKER/$TOPIC"
  sleep 5
done

curlのMQTT利用における制限

curlはテストやスクリプト用途に便利ですが、以下の制限があります：

制限事項	説明
QoS 0のみ対応	QoS 1や2はサポートされていない
バイナリ出力	サブスクライブ出力は整形されない
ワイルドカード非対応	`+`や`#`によるサブスクライブ不可
単一トピックのみ	1コマンドで1トピックのみ対応
永続セッションなし	ステートレスな接続

高度なMQTT機能が必要な場合は、MQTTX CLIやEMQXクライアントSDKの利用を推奨します。

curlでMQTTサポートを確認する

bash

curl --version | grep -i mqtt

mqtt（curl ≥ 8.19.0ならmqttsも）が表示されればMQTT対応ビルドです。表示されない場合は：

curlを7.70.0以上にアップグレードする
MQTT対応ビルドをインストールする
ソースから--enable-mqttオプション付きでビルドする

トラブルシューティング

curlとEMQX利用時のよくある問題と対処法を紹介します。

接続拒否またはタイムアウト

症状

Connection refused
Failed to connect to broker
接続がハングしタイムアウトする

原因の可能性

ブローカーアドレスやポートの誤り
ネットワークファイアウォールによるMQTT/MQTTSポートの遮断
ブローカーが起動していない、または指定ポートでリスニングしていない

対策

ブローカーアドレスとポートを確認
- MQTT：1883
- MQTTS：8883
詳細モードでネットワーク接続を確認

bash

curl -v mqtt://broker.emqx.io/curl/test

curlでMQTTまたはMQTTSがサポートされていない

症状

Protocol "mqtt" not supported
Unknown protocol

原因の可能性

MQTT対応なしでビルドされたcurlを使用している
curlのバージョンが古い

対策

プロトコルサポートを確認

bash

curl --version

mqtt（およびTLS用のmqtts）がProtocolsに含まれているか確認。

curlをアップグレード、またはMQTT対応ビルドをインストール

TLSハンドシェイクや証明書エラー（MQTTS）

症状

SSL certificate problem
TLS handshake failed
Unable to get local issuer certificate

原因の可能性

CA証明書が不足または誤っている
ブローカーがプライベートまたは自己署名証明書を使用している

対策

CA証明書を明示的に指定

bash

curl --cacert /path/to/ca.crt \
  mqtts://your-broker.example.com/topic

テスト目的で検証をスキップ（本番非推奨）

bash

curl -k mqtts://your-broker.example.com/topic

サブスクライブ時にメッセージが受信できない

症状

サブスクライブコマンドは実行されるが出力がない

原因の可能性

出力バッファリングが有効
トピックにメッセージがパブリッシュされていない
トピック名の不一致

対策

サブスクライブ時は必ず-Nを使う

bash

curl -N mqtt://broker.emqx.io/curl/test

メッセージが同じトピックにパブリッシュされているか確認

認証失敗

症状

接続が即座に切断される
ブローカーのログに認証や認可エラーが記録される

原因の可能性

ユーザー名またはパスワードの誤り
トピックに対するACL制限

対策

認証情報を確認

bash

curl -u "username:password" \
  mqtts://your-broker.example.com/topic

EMQXの認証設定とACLを確認

さらに詳しく

curlを使ったMQTT/MQTTSの接続、パブリッシュ、サブスクライブの詳細な手順や背景説明、追加例、利用上の注意点については、以下のブログ記事をご覧ください：

Using curl for MQTT: Connect, Publish, and Subscribe with Secure IoT Communication

本ブログは本Enterprise向けガイドの補完として、より深い解説と拡張例を提供しています。

JT/T 808 ゲートウェイ

GB/T 32960 ゲートウェイ

Volcengine RTC

シナリオ

GPT-Realtime

EMQXでcurlを使う ​

curlのバージョン要件 ​

MQTTブローカーのセットアップ ​

EMQXパブリックブローカー（テスト用） ​

EMQX Enterpriseのデプロイメント ​

curlでEMQX Enterpriseに接続する ​

curlのMQTT URLスキームの理解 ​

curlのMQTT出力フォーマット ​

トピックのサブスクライブ ​

基本的なサブスクライブ（暗号化なし） ​

MQTTSによるセキュアサブスクライブ（curl ≥ 8.19.0） ​

認証付きサブスクライブ ​

MQTTメッセージのパース ​

Bashのワンライナー例 ​

生データをファイルに保存して確認 ​

再利用可能なシェル関数 ​

メッセージのパブリッシュ ​

基本的なパブリッシュ（暗号化なし） ​

MQTTSによるセキュアパブリッシュ（curl ≥ 8.19.0） ​

JSONペイロードのパブリッシュ ​

認証付きパブリッシュ ​

主要なcurlオプション ​

TLS設定（MQTTS） ​

CA証明書による検証 ​

相互TLS（mTLS） ​

よくあるユースケース ​

ブローカー接続テスト ​

シェルスクリプトやIoTプロトタイピング ​

curlのMQTT利用における制限 ​

curlでMQTTサポートを確認する ​

トラブルシューティング ​

接続拒否またはタイムアウト ​

curlでMQTTまたはMQTTSがサポートされていない ​

TLSハンドシェイクや証明書エラー（MQTTS） ​

サブスクライブ時にメッセージが受信できない ​

認証失敗 ​

さらに詳しく ​

EMQXでcurlを使う

curlのバージョン要件

MQTTブローカーのセットアップ

EMQXパブリックブローカー（テスト用）

EMQX Enterpriseのデプロイメント

curlでEMQX Enterpriseに接続する

curlのMQTT URLスキームの理解

curlのMQTT出力フォーマット

トピックのサブスクライブ

基本的なサブスクライブ（暗号化なし）

MQTTSによるセキュアサブスクライブ（curl ≥ 8.19.0）

認証付きサブスクライブ

MQTTメッセージのパース

Bashのワンライナー例

生データをファイルに保存して確認

再利用可能なシェル関数

メッセージのパブリッシュ

基本的なパブリッシュ（暗号化なし）

MQTTSによるセキュアパブリッシュ（curl ≥ 8.19.0）

JSONペイロードのパブリッシュ

認証付きパブリッシュ

主要なcurlオプション

TLS設定（MQTTS）

CA証明書による検証

相互TLS（mTLS）

よくあるユースケース

ブローカー接続テスト

シェルスクリプトやIoTプロトタイピング

curlのMQTT利用における制限

curlでMQTTサポートを確認する

トラブルシューティング

接続拒否またはタイムアウト

curlでMQTTまたはMQTTSがサポートされていない

TLSハンドシェイクや証明書エラー（MQTTS）

サブスクライブ時にメッセージが受信できない

認証失敗

さらに詳しく