EMQXでcurlを使う

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

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

本ページでは、EMQXとcurlを使った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（ServerlessまたはDedicated）にも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]：省略可能なポート番号。指定がない場合はデフォルトを使用：
- 1883（mqtt://の場合）
- 8883（mqtts://の場合）
/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はサブスクライブ時にMQTTメッセージをバイナリ形式で出力します。整形されたテキスト形式ではありません。

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

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ハンドシェイクを検証します。

接続成功の目安

ブローカーのホスト名が1つ以上の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やQoS 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向けガイドを補完し、より深い解説と拡張例を提供しています。

Kubernetes

EMQX Operator

EMQX クラスター管理

API リファレンス

パスワード認証

監視

アクセスコントロール

統合

管理

Prometheus との統合

OpenTelemetry との統合

エンドツーエンドトレース

プラグインカタログ

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）

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

認証失敗

さらに詳しく