== fubar ==
An MQTT message broker written in erlang targeted to support internet scale applications.

== Getting Started ==
1. Getting dependencies and building
	$ make deps
	$ make
	
2. Starting a broker in interactive mode
	$ make test
	
3. Testing
	3.1. Starting a node for client
		$ make client
	
	3.2. Connecting clients (in the erlang shell)
		1> C1 = mqtt_client:start([{client_id, <<"c1">>}]).
		2> C2 = mqtt_client:start([{client_id, <<"c2">>}]).
	
	3.3. Subscribing and publishing messages
		3> C1 ! mqtt:subscribe([{topics, [<<"t1">>]}]).
		4> C2 ! mqtt:publish([{topic, <<"t1">>}, {payload, <<"hello!">>}]).
	
4. Shutting down the broker gracefully.
	(fubar@host)1> fubar:stop().
	(fubar@host)2> q().

== More Features ==
1. Adding a new broker node to existing broker cluster
	$ make test master_node=name@host
	
	Note) If you want to more than one broker node in a computer,
	You have to use different node name and listen port as:
	$ make test master=name@host node=other mqtt_port=1884
	
2. Using account control
	Modify {auth, undefined} in src/fubar.app.src as {auth, mqtt_account}.
	Then, call mqtt_account:update/2 as:
	(fubar@host)1> mqtt_account:update(<<"romeo">>, <<"1234">>).
	
3. More parameters for a client
	Full list of client parameters are:
	1> C3 = mqtt_client:start([{hostname, "localhost"},
	                           {port, 1884},
	                           {username, <<"romeo">>},
	                           {password, <<"1234">>},
	                           {client_id, <<"c1">>},
	                           {keep_alive, 60},
	                           clean_session,
	                           {will_topic, <<"will">>},
	                           {will_message, <<"bye-bye">>},
	                           {will_qos, at_least_once},
	                           will_retain]).
	
4. Starting a broker in daemon mode
	Use 'run' instead of 'test'.
	$ make run
	
	Note) You may not start more than one daemon in a machine.

5. Getting a daemon shell
	$ make debug
	
	If you are debuggin from remote machine (port defaults to ssh 22):
	$ make debug host=xxx.xxx.xxx.xxx port=xx
	
	Note) The debug shell is closely bound with the daemon.  If you exit from
	the debug shell in a normal way, the daemon will stop.  Close or kill the
	debug shell process (ssh) to prevent the daemon from being terminated.
	
6. Broker state is preserved
	The broker restores all the state -- accounts, topics and subscriptions - on restart.
	To clear this state, do:
	$ make reset
		
7. Dumping logs to text files
	SASL logs can be taken as:
	$ make log
	
	SASL logs show events happened in the start-up process and events not dealt with
	by the application.
	
	Application logs can be taken from the shell as:
	(fubar@host)1> fubar_log:dump(trace, "trace.log").
	
	Log classes are:
	- packet	% bytes sent and received by the broker
	- protocol	% mqtt messages sent and received by the broker
	- resource	% long lasting resources such as sessions and topics
	- trace		% fubar packets marked as trace
	- warning	% abnormal conditions that are not considered critical
	- debug		% message put for debugging purpose
	- noise		% irrelevant events taken but dropped
	
8. Log management
	Start up log classes can be controlled in the fubar application meta file, src/fubar.app.src.
	~         {fubar_log, [{dir, "priv/log"},
	~                      {max_bytes, 10485760},
	~                      {max_files, 10},
	~                      {classes, [trace, error]}
	~                     ]},
	
	Other log classes - warning, info or debug - can be turned on/off by putting
	them in the meta file or at runtime by calling fubar_log:open/1.
	(fubar@host)1> fubar_log:open(debug).
	
	After turning a log class on, fubar_log:show/1, fubar_log:hide/1 controls
	whether or not to print the log in the shell.
	(fubar@host)2> fubar_log:show(debug).
	(fubar@host)3> fubar_log:hide(trace).
	
	Without regard to the show/hide status of a log class, logs in the class
	are stored in filesystem until fubar_log:close/1 is called.

9. SSL support
	9.1. Prepare a certificate authority
		$ cd priv/ssl/ca
		$ mkdir certs private
		$ chmod 700 private
		$ echo 01 > serial
		$ touch index.txt
		
		Put your hostname in line 39 of openssl.cnf
		$ vi openssl.cnf
		~ [ root_ca_distinguished_name ]                             
		~ commonName = hostname                                      
		
		Then, run openssl to generate a certificate.
		$ openssl req -x509 -config openssl.cnf -newkey rsa:2048 -days 365 \
			-out cacert.pem -outform PEM -subj /CN=fubar_ca/ -nodes
		$ openssl x509 -in cacert.pem -out cacert.cer -outform DER
	
	9.2. Create a server certificate
		$ cd ..
		$ openssl genrsa -out key.pem 2048
		$ openssl req -new -key key.pem -out req.pem -outform PEM \
			-subj /CN=$(hostname)/O=server/ -nodes
		$ openssl ca -config ca/openssl.cnf -in req.pem -out cert.pem -notext \
			-batch -extensions server_ca_extensions
		$ openssl pkcs12 -export -out keycert.p12 -in cert.pem -inkey key.pem \
			-passout pass:MyPassword
	
	9.3. Testing
		Use mqtts_port command line parameter to start an SSL listener when starting the broker.
		$ make test mqtts_port=1882
		(fubar@host)1>
		
		Now use {transport, ranch_ssl} option on the client side.
		$ make client
		1> ssl:start().
		2> mqtt_client:start([{port, 1882},{transport, ranch_ssl},{client_id, <<"ssltest">>}]).