== 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 client 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=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,
	                           socket_options, [...]]).
	
	Refer inet:setopts/2 for socket_options.
	
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
	
	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.  Use CTRL-D to stop
	debugging.
	
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").
	
	Or you can dump all the logs by:
	(fubar@host)1> fubar_log:dump().
	
	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, hide}, {warning, show}]}
	~                     ]},
	
	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 to screen.
	(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 open
	classes 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
		$ 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
		$ openssl genrsa -out ../key.pem 2048
		$ openssl req -new -key ../key.pem -out ../req.pem -outform PEM \
			-subj /CN=SomeHostName/O=YourOrganizationName/ -nodes
		$ openssl ca -config openssl.cnf -in ../req.pem -out ../cert.pem
			-notext -batch -extensions server_ca_extensions
		$ openssl pkcs12 -export -in ../cert.pem -out ../keycert.p12 \
			-inkey ../key.pem -passout pass:YourPassword
		
		The processes in 9.1 and 9.2 are stored in batch script
		priv/ssl/ca/new-certs.sh.  So you can just,
		
		$ cd priv/ssl/ca
		$ ./new-certs.sh
		
	9.3. Testing
		Use mqtts_port command line parameter to start an SSL listener when
		starting the broker.
		$ cd ../../..
		$ make test mqtts_port=8883
		(fubar@host)1>
		
		Test basic connection with openssl s_client.
		$ openssl s_client -connect localhost:8883
		
		If it succeeds, use {transport, ranch_ssl} option on the client side.
		$ make client
		1> ssl:start().
		2> mqtt_client:start([{port, 8883},{transport, ranch_ssl},
			{client_id, <<"ssltest">>}]).