shishenkov / cumulusadmin

A database backed administration tool for Cumulus, an open RTMFP server

CumulusAdmin

CumulusAdmin is a database-backed administration tool for Cumulus, an open source RTMFP server.

The server side code has been written in LUA that is provided natively by Cumulus. The administration tool itself has been written in PHP and by default it is configured to be backed by a MySQL database. Though, other databases should work, too. We use it at OpenRTMFP.net for maintainance and hereby commit it to the Cumulus community for that it will be helpful.

Features

• Easily manage the vital parts of Cumulus on the fly without the requirement to write LUA or to restart the server
• Manage developers and applications via your database
• Manage developers' connect keys
• Manage applications identified by a unique path
• Enable/disable certain developers and applications
• Configure if publishing is allowed for client->server streams
• If allowed, optionally set a publishing password
• Add subscribe/unsubscribe callbacks for publisher->server->subscriber streams to notify the publisher about its publication's subscribers
• Holds a complete image of clients, groups and publications inside the database, e.g. for live statistics
• Keeps track of the client->server traffic consumed by each application by direction and type
• Easily configurable through CumulusServer.ini

SQL scheme

Table "developers":

• id:Number
• enabled:0|1
• connectkey:String|NULL
• contact:String|NULL
• password:String|NULL

Table "applications":

• id:Number
• enabled:0|1
• started:0|1
• path:String
• developer_id:Number → developers.id
• allow_publish:0|1
• publish_password:String|NULL
• subscribe_callback:String|NULL
• unsubscribe_callback:String|NULL
• start_time:Number[timestamp]
• stop_time:Number[timestamp]
• traffic:Number[bytes]
• traffic_audio:Number[bytes]
• traffic_video:Number[bytes]
• traffic_data:Number[bytes]
• traffic_in:Number[bytes]
• traffic_audio_in:Number[bytes]
• traffic_video_in:Number[bytes]
• traffic_data_in:Number[bytes]
• traffic_out:Number[bytes]
• traffic_audio_out:Number[bytes]
• traffic_video_out:Number[bytes]
• traffic_data_out:Number[bytes]

Traffic is measured in overall packet content bytes. It does not contain overhead generated by the protocol. You can easily query the generated values to create graphs drawn over time or similar from it.

Table "clients":

• id:String
• application_id:Number → applications.id
• address:String[ip:port]
• pageUrl:String|NULL
• swfUrl:String|NULL
• flashVersion:String[e.g. WIN 11,2,202,233]|NULL
• connect_time:Number[timestamp]

Table "groups": Holds all current groups

• application_id:Number → applications.id
• id:String
• members:Number
• create_time:Number[timestamp]

Table "groups_clients": Holds group members

• group_id:String → groups.id
• client_id:String → clients.id
• join_time:Number[timestamp]

Table "publications": Holds publications by client

• application_id:Number → applications.id
• client_id:String → clients.id
• name:String
• subscribers:Number
• publish_time:Number[timestamp]

Table "publications_clients": Holds subscribed clients by publication

• publication_name:String → publications.name
• client_id:String → clients.id
• subscribe_time:Number[timestamp]

Installation

• Create the database. You can use the included sql/cumulus.sql to set up an InnoDB scheme with properly connected foreign keys.
• Copy the included lua/main.lua to CumulusServer/www/main.lua
• Create or edit your CumulusServer.ini and add your database configuration. You can use the included conf/CumulusServer-example.ini as a starting point.
• Create developers and applications inside the database. A very basic example is already included in sql/cumulus.sql.

Usage

• To add a new developer, insert one into the "developers" table.
• To add a new application, insert one into the "applications" table and create the corresponding directory in CumulusServer/www including an empty main.lua. If you are going to add the application "/example", you just create the directory and an empty main.lua at CumulusServer/www/example/main.lua
• To allow everyone to publish client->server streams, set the "allow_publish" field for the desired application to "1" and leave the "publish_password" empty.
• To allow everyone who knows the correct password to publish client->server streams, set the "allow_publish" field for the desired application to "1" and set a "publish_password"
• To not allow anyone to publish client->server streams i.e. to allow P2P only, set the "alllow_publish" field to "0"
• To connect to an application, use:

// For an application with path="/example" associated to a developer with connectkey="MyDeveloperKey"
var con:NetConnection = new NetConnection();
con.connect("/example", "MyDeveloperConnectKey");

// If the developer has not set a connectkey then just any password will work, or you may simply use:
con.connect"/example");

• To handle subscribe/unsubscribe callbacks, set the callback names for the application you want to use them with in the database and attach a custom client listener to your NetStream instance that you have connected with the NetStream.CONNECT_TO_FMS flag:

// ActionScript 3
var ns:NetStream = new NetStream(con, NetStream.CONNECT_TO_FMS);
var c:Object = new Object;

// Example for subscribe_callback="onRelayConnected" and unsubscribe_callback="onRelayDisconnected"

c.onRelayConnected = function(publicationName:String, peerId:String, total:Number):void {
	trace("Peer "+peerId+" connected to publication "+publicationName+" (now "+total+" total subscribers)");
}
c.onRelayDisconnected = function(publicationName:String, peerId:String, remaining:Number):void {
	trace("Peer "+peerId+" disconnected from publication "+publicationName+" (now "+remaining+" remaining subscribers)")
}
ns.client = c;
// ...

// For allow_publish="1"
ns.publish("somePublicationName");

// ...or if you have also set publish_password="somePassword"
ns.publish("somePublicationName", "somePassword");

• To get an overview of the current clients, groups and publications statistics simply query the "clients", "groups" and "publications" tables. These contain a complete image of the current state of CumulusServer. The tables "groups_clients" and "publications_clients" contain the corresponding relational mapping between these relations. The "applications" table contains traffic information for every single application.
• To enable/disable developers or applications just change the "enabled" property of the corresponding object in your database.

Extending CumulusAdmin

It's easy to extend CumulusAdmin from within applications. Just make sure to call www:implementedMethod(...) when implementing one of Cumulus' various event handlers. Let's say that www/main.lua already contains CumulusAdmin and you are creating a new application named "example" and want to use the onConnection handler. Then you'd write in www/example/main.lua:

function onConnection(client, response, connectkey, ...)
	local error = www:onConnection(client, response, connectkey)
	if error ~= nil then
		return error
	end
	...custom application code...
end

This will work because CumulusAdmin will never return "true" but "nil" if everything is fine. If something goes wrong, e.g. the connectkey is invalid, it will return something else than "nil" and so should you instead of executing your custom code. This way it can be guaranteed that the internal image CumulusAdmin creates of all clients, publications, groups etc. will retain its integrity.

Things still to do

• Easy to use PHP administration frontend
• Decide what to do about the requirement to create empty directories with empty main.lua's for each application (one idea: explicitly return "true")

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.