GetStarted
This commit is contained in:
Feng Lee
parent
5d9159cfc9
commit
aa6dc3e689
|
|
@ -1,199 +0,0 @@
|
|||
# eMQTT Get Started
|
||||
|
||||
## Overview
|
||||
|
||||
eMQTT is a clusterable, massively scalable, fault-tolerant and extensible MQTT V3.1/V3.1.1 broker written in Erlang/OTP.
|
||||
|
||||
eMQTT is aimed to provide a solid-stable broker that could be clusterd to support millions of connections and clients.
|
||||
|
||||
## Requires
|
||||
|
||||
eMQTT is cross-platform, could run on windows, linux, freebsd and mac os x.
|
||||
|
||||
eMQTT requires Erlang R17+ to build from source.
|
||||
|
||||
## Featues
|
||||
|
||||
### Full MQTT V3.1.1 Support
|
||||
|
||||
MQTT V3.1.1 and V3.1 protocol support
|
||||
|
||||
QoS0, QoS1, QoS2 Publish and Subscribe
|
||||
|
||||
Session Management and Offline Messages
|
||||
|
||||
Retained Messages
|
||||
|
||||
Passed eclipse paho interoperability tests
|
||||
|
||||
### Clusterable, Massively Scalable
|
||||
|
||||
Massive Connections Clients Support
|
||||
|
||||
Cluster brokers on servers or cloud hosts
|
||||
|
||||
Bridge brokers locally or remotelly
|
||||
|
||||
## Download, Install
|
||||
|
||||
### Download
|
||||
|
||||
Dowload binary packages from [http://emqtt.io/downloads](http://emqtt.io/downloads].
|
||||
|
||||
Please build from source if no packages for your platform, or contact us.
|
||||
|
||||
### Install
|
||||
|
||||
Extract tgz package to your installed directory. for example:
|
||||
|
||||
```
|
||||
tar xvf emqtt-ubuntu64-0.3.0-beta.tgz && cd emqtt
|
||||
```
|
||||
|
||||
### Startup
|
||||
|
||||
Startup console for debug:
|
||||
|
||||
```
|
||||
cd emqtt && ./bin/emqtt console
|
||||
```
|
||||
|
||||
You could see all RECV/SENT MQTT Packages on console.
|
||||
|
||||
Start as daemon:
|
||||
|
||||
```
|
||||
cd emqtt && ./bin/emqtt start
|
||||
```
|
||||
|
||||
eMQTT occupies 1883 port for MQTT, 8083 for HTTP API.
|
||||
|
||||
### Status
|
||||
|
||||
```
|
||||
cd emqtt && ./bin/emqtt_ctl status
|
||||
```
|
||||
|
||||
### Stop
|
||||
|
||||
```
|
||||
cd emqtt && ./bin/emqtt stop
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### etc/app.config
|
||||
|
||||
```
|
||||
{emqtt, [
|
||||
%Authetication. Internal, Anonymous Default.
|
||||
{auth, {anonymous, []}},
|
||||
{access, []},
|
||||
{session, [
|
||||
{expires, 1}, %hours
|
||||
{max_queue, 1000},
|
||||
{store_qos0, false}
|
||||
]},
|
||||
{retain, [
|
||||
{store_limit, 100000}
|
||||
]},
|
||||
{listen, [
|
||||
{mqtt, 1883, [
|
||||
{acceptors, 4},
|
||||
{max_conns, 1024}
|
||||
]},
|
||||
{http, 8083, [
|
||||
{acceptors, 1},
|
||||
{max_conns, 512}
|
||||
]}
|
||||
]}
|
||||
]}
|
||||
```
|
||||
|
||||
### etc/vm.args
|
||||
|
||||
```
|
||||
-name emqtt@127.0.0.1
|
||||
|
||||
-setcookie emqtt
|
||||
```
|
||||
|
||||
## Cluster
|
||||
|
||||
Suppose we cluster two nodes on 'host1', 'host2', Steps:
|
||||
|
||||
### configure and start node on host1
|
||||
|
||||
configure 'etc/vm.args':
|
||||
|
||||
```
|
||||
-name emqtt@host1
|
||||
```
|
||||
|
||||
then start:
|
||||
|
||||
```
|
||||
./bin/emqtt start
|
||||
```
|
||||
|
||||
### configure and start node on host2
|
||||
|
||||
configure 'etc/vm.args':
|
||||
|
||||
```
|
||||
-name emqtt@host2
|
||||
```
|
||||
|
||||
```
|
||||
./bin/emqtt start
|
||||
```
|
||||
|
||||
### cluster two nodes
|
||||
|
||||
Cluster from 'host2':
|
||||
|
||||
```
|
||||
./bin/emqtt_ctl cluster emqtt@host1
|
||||
```
|
||||
|
||||
or cluster from 'host1':
|
||||
|
||||
```
|
||||
./bin/emqtt_ctl cluster emqtt@host2
|
||||
```
|
||||
|
||||
then check clustered nodes on any host:
|
||||
|
||||
```
|
||||
./bin/emqtt_ctl cluster
|
||||
```
|
||||
|
||||
## HTTP API
|
||||
|
||||
eMQTT support HTTP API to publish message from your APP to MQTT client.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
curl -v --basic -u user:passwd -d "qos=1&retain=0&topic=/a/b/c&message=hello from http..." -k http://localhost:8083/mqtt/publish
|
||||
```
|
||||
|
||||
### URL
|
||||
|
||||
```
|
||||
HTTP POST http://host:8083/mqtt/publish
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
Name | Description
|
||||
--------|---------------
|
||||
qos | QoS(0, 1, 2)
|
||||
retain | Retain(0, 1)
|
||||
topic | Topic
|
||||
message | Message
|
||||
|
||||
## Contact
|
||||
|
||||
feng@emqtt.io
|
||||
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
# eMQTT Desgin Guide
|
||||
|
||||
## KeepAlive
|
||||
|
||||
## Retained
|
||||
|
||||
## QOS1
|
||||
|
||||
## QOS2
|
||||
|
||||
## Durable Subscriptions
|
||||
|
||||
Durable Sub:
|
||||
|
||||
Client->Queue->Router->Queue->Client
|
||||
|
||||
Normal Sub:
|
||||
|
||||
Client->Router->Client
|
||||
|
||||
Router to register queues
|
||||
|
||||
## Topic Tree
|
||||
|
||||
## Offline Message
|
||||
|
||||
## ACL
|
||||
|
||||
## Authentication with clientId
|
||||
|
||||
## SSL/TLS Socket
|
||||
|
||||
## $SYS/topics and Broker statistics...
|
||||
|
||||
## Cluster
|
||||
|
||||
## Bridge
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
# MQTT Protocol Guide
|
||||
|
||||
## Server or Broker
|
||||
|
||||
A program or device that acts as an intermediary between Clients which publish Application Messages and Clients which have made Subscriptions.
|
||||
|
||||
A Server Accepts Network Connections from Clients.
|
||||
Accepts Application Messages published by Clients.
|
||||
Processes Subscribe and Unsubscribe requests from Clients.
|
||||
Forwards Application Messages that match Client Subscriptions.
|
||||
|
||||
|
||||
Client ----> Broker(Server) ----> Client
|
||||
|
||||
Publisher ----> Broker -----> Subscriber
|
||||
|
||||
## Subscription and Session
|
||||
|
||||
### Subscription
|
||||
|
||||
A Subscription comprises a Topic Filter and a maximum QoS. A Subscription is associated with a single Session. A Session can contain more than one Subscription. Each Subscription within a session has a different Topic Filter.
|
||||
|
||||
### Session
|
||||
|
||||
A stateful interaction between a Client and a Server. Some Sessions last only as long as the Network
|
||||
|
||||
Connection, others can span multiple consecutive Network Connections between a Client and a Server.
|
||||
|
||||
## Topic Name and Filter
|
||||
|
||||
An expression contained in a Subscription, to indicate an interest in one or more topics. A Topic Filter can include wildcard characters.
|
||||
|
||||
|
||||
## Packet Identifier
|
||||
|
||||
|
||||
|
|
@ -1,133 +0,0 @@
|
|||
## Quick Start
|
||||
|
||||
## Startup in Five Minutes
|
||||
|
||||
```
|
||||
$ git clone git://github.com/emqtt/emqttd.git
|
||||
|
||||
$ cd emqttd
|
||||
|
||||
$ make && make dist
|
||||
|
||||
$ cd rel/emqttd
|
||||
|
||||
$ ./bin/emqttd console
|
||||
```
|
||||
|
||||
## Deploy and Start
|
||||
|
||||
### start
|
||||
|
||||
```
|
||||
cp -R rel/emqttd $INSTALL_DIR
|
||||
|
||||
cd $INSTALL_DIR/emqttd
|
||||
|
||||
./bin/emqttd start
|
||||
|
||||
```
|
||||
|
||||
### stop
|
||||
|
||||
```
|
||||
./bin/emqttd stop
|
||||
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### etc/app.config
|
||||
|
||||
```
|
||||
{emqttd, [
|
||||
{auth, {anonymous, []}}, %internal, anonymous
|
||||
{listen, [
|
||||
{mqtt, 1883, [
|
||||
{acceptors, 4},
|
||||
{max_clients, 1024}
|
||||
]},
|
||||
{mqtts, 8883, [
|
||||
{acceptors, 4},
|
||||
{max_clients, 1024},
|
||||
%{cacertfile, "etc/ssl/cacert.pem"},
|
||||
{ssl, [{certfile, "etc/ssl.crt"},
|
||||
{keyfile, "etc/ssl.key"}]}
|
||||
]},
|
||||
{http, 8083, [
|
||||
{acceptors, 1},
|
||||
{max_clients, 512}
|
||||
]}
|
||||
]}
|
||||
]}
|
||||
|
||||
```
|
||||
|
||||
### etc/vm.args
|
||||
|
||||
```
|
||||
|
||||
-name emqttd@127.0.0.1
|
||||
|
||||
-setcookie emqtt
|
||||
|
||||
```
|
||||
|
||||
When nodes clustered, vm.args should be configured as below:
|
||||
|
||||
```
|
||||
-name emqttd@host1
|
||||
```
|
||||
|
||||
## Cluster
|
||||
|
||||
Suppose we cluster two nodes on 'host1', 'host2', Steps:
|
||||
|
||||
on 'host1':
|
||||
|
||||
```
|
||||
./bin/emqttd start
|
||||
```
|
||||
|
||||
on 'host2':
|
||||
|
||||
```
|
||||
./bin/emqttd start
|
||||
|
||||
./bin/emqttd_ctl cluster emqttd@host1
|
||||
```
|
||||
|
||||
Run './bin/emqttd_ctl cluster' on 'host1' or 'host2' to check cluster nodes.
|
||||
|
||||
## HTTP API
|
||||
|
||||
emqttd support http to publish message.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
curl -v --basic -u user:passwd -d "qos=1&retain=0&topic=a/b/c&message=hello from http..." -k http://localhost:8083/mqtt/publish
|
||||
```
|
||||
|
||||
### URL
|
||||
|
||||
```
|
||||
HTTP POST http://host:8083/mqtt/publish
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
Name | Description
|
||||
--------|---------------
|
||||
qos | QoS(0, 1, 2)
|
||||
retain | Retain(0, 1)
|
||||
topic | Topic
|
||||
message | Message
|
||||
|
||||
|
||||
## Contributors
|
||||
|
||||
@hejin1026 <260495915 at qq.com>
|
||||
|
||||
@desoulter <assoulter123 at gmail.com>
|
||||
|
||||
@turtleDeng
|
||||
|
|
@ -1,6 +0,0 @@
|
|||
# Retained Message
|
||||
|
||||
## API
|
||||
|
||||
store(
|
||||
|
||||
19
doc/route.md
19
doc/route.md
|
|
@ -1,19 +0,0 @@
|
|||
|
||||
|
||||
ClientA -> SessionA -> Route -> PubSub -> SessionB -> ClientB
|
||||
|
||||
|
||||
ClientA -> Session -> PubSub -> Route -> SessionB -> ClientB
|
||||
| |
|
||||
Trie Subscriber
|
||||
|
||||
|
||||
ClientPidA -> ClientPidB
|
||||
|
||||
|
||||
ClientPidA -> SessionPidB -> ClientB
|
||||
|
||||
|
||||
ClientPidA -> SessionPidA -> SessionPidB -> ClientPidB
|
||||
|
||||
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
# Session Design
|
||||
|
||||
## session manager
|
||||
|
||||
```erlang
|
||||
|
||||
%% lookup sesssion
|
||||
emqtt_sm:lookup_session(ClientId)
|
||||
|
||||
%% Start new or resume existing session
|
||||
emqtt_sm:start_session(ClientId)
|
||||
|
||||
%% destroy session, discard all data
|
||||
emqtt_sm:destory_session(ClientId)
|
||||
|
||||
%% close session, save all data
|
||||
emqtt_sm:close_session(ClientId)
|
||||
```
|
||||
|
||||
## session supervisor
|
||||
|
||||
usage?
|
||||
|
||||
## session
|
||||
|
||||
```
|
||||
%%system process
|
||||
process_flag(trap_exit, true),
|
||||
|
||||
session:start()
|
||||
session:subscribe(
|
||||
session:publish(
|
||||
session:resume(
|
||||
session:suspend(
|
||||
%%destory all data
|
||||
session:destory(
|
||||
%%save all data
|
||||
session:close()
|
||||
|
||||
```
|
||||
|
||||
## sm and session
|
||||
|
||||
sm manage and monitor session
|
||||
|
||||
## client and session
|
||||
|
||||
client(normal process)<--link to -->session(system process)
|
||||
|
||||
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
|
||||
|
||||
client state --> parse_state
|
||||
--> proto_state --> session_state
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
# eMQTT $SYS Topics
|
||||
|
||||
Wiki: [$SYS Topics of Broker](https://github.com/emqtt/emqtt/wiki/$SYS-Topics-of-Broker)
|
||||
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
# eMQTT User Guide
|
||||
|
||||
## Introduction
|
||||
|
||||
## Installation
|
||||
|
||||
### Install Requirements
|
||||
|
||||
## Configuration
|
||||
|
||||
## Cluster
|
||||
|
||||
## Bridge
|
||||
|
||||
Loading…
Reference in New Issue