Emanagement guide
Emanagement it's a ruby script that provides important functions to manage ejabberd rosters and other features using ejabberdctl, a control interface of Ejabberd server, designed to help the administrator control the functioning of the running ejabberd daemon.
We assume that the reader has some knowledge in XMPP protocol, otherwise, take a look at the XMPP RFC.
-
Jabber Identifiers (JIDs) uniquely identify individual entities in the Jabber network. Read more.
-
In XMPP, one's contact list is called a roster, which consists of any number of specific roster items, each roster item being identified by a unique JID (usually of the form contact@domain). A user's roster is stored by the user's server on the user's behalf so that the user may access roster information from any resource.
-
In order to protect the privacy of instant messaging users and any other entities, presence and availability information is disclosed only to other entities that the user has approved. When a user has agreed that another entity may view its presence, the entity is said to have a subscription to the user's presence information.
Subscription types::
-> none: The user does not have a subscription to the contact's presence information, and the contact does not have a subscription to the user's presence information.
-> to: The user has a subscription to the contact's presence information, but the contact does not have a subscription to the user's presence information.
-> from: The contact has a subscription to the user's presence information, but the user does not have a subscription to the contact's presence information.
-> both: Both the user and the contact have subscriptions to each other's presence information.
As we can see in the Social Stream Presence architecture scheme, our Xmpp Server only stores users's roster, it don't stores usernames and passwords, the authentication service is provided by the Social Stream Rails Application, therefore we will not have registered users in our xmpp server.
In Social Stream, the user's JID has the following structure: slug@domain .
Social Stream user's slug is building from the name, converting it to lowercase and replacing spaces with underscores. For example, if the user name is "Jonh Doe", the slug will be "jonh-doe".
If a user wants to know his slug, he can visit http://domain/api/me after log in, and get it from the slug's tag <slug>user's slug</slug>.
Shoulders to the wheel!
- Reflect Social Stream's contacts to rosters.
- Managing rosters with Emanagement
- Managing stanzas with Emanagement
- Adding new features to Emanagement
We assume that the reader is already familiar with Social Stream Base.
- A contact is a link between two actors.
- Each contact has many ties, which determine the kind of the link through relations.
- Each activity is attached to a contact. The sender of the contact is the author of the activity and the receiver actor of the contact is the receiver of the activity.
In this guide, in a simple way, we will only differentiate between two types of contacts:
- Unidirectional: When the contact in the other way isn't established (or negative replied).
-
Bidirectional: When the contact in the other way is established and positive replied.
When the unidirectional contact is established the sender ( User A ) adds the receiver ( User B ) to his roster with subscription type from.
When the unidirectional contact is established and positive replied in the other way, the bidirectional contact is established. In this case the sender adds the receiver to his roster with subscription type both and the receiver adds the sender to his roster with subscription type both too.
Unidirectional Social Stream contacts are reflected to xmpp rosters using this emagement function:
addBuddyToRoster userJid buddyJid buddyNick buddyGroup subscription_type
that can be executed by this ruby function:
SocialStream::Presence::XmppServerOrder::addBuddyToRoster(userJid,buddyJid,buddyNick,buddyGroup,subscription_type)
Bidirectional Social Stream contacts are reflected to xmpp rosters using this emagement function:
setBidireccionalBuddys userAJid userBJid userANick userBNick groupForA groupForB
that can be executed by this ruby function:
SocialStream::Presence::XmppServerOrder::setRosterForBidirectionalTie(userAJid,userBJid,userANick, userBNick,groupForA,groupForB)
A buddy it's just a roster item, a contact added to a roster.
When a Social Stream contact is created or updated, the corresponding emanagement function will be called automatically, and the changes will be reflected in the ejabberd database.
However, emanagement provides more functions to manage rosters, that can help us in testing and maintenance tasks:
addBuddyToRoster userJid buddyJid buddyNick buddyGroup subscription_type
removeBuddyFromRoster userJid buddyJid
setBidireccionalBuddys userAJid userBJid userANick userBNick groupForA groupForB
unsetBidireccionalBuddys userJid oldFriendJid oldFriendNick groupForOldFriend
getRoster userJid
removeRoster userJid
removeAllRostersByDomain domain
removeAllRosters
getAllUserJidsWithRosterByDomain domain
printAllRostersByDomain domain
printAllBidirecctionalBuddysByDomain domain
checkUserJid userJid
checkBidirecctionalBuddys userAJid userBJid
For example, to get the roster of a user with slug demo:
admin@localhost:~/ejabberd_scripts$ ./emanagement getRoster demo
------------------------
Init Ejabberd Maintenance script
------------------------
pamela-hall@localhost Pamela both none SocialStream
terry-alvarez@localhost Terry both none SocialStream
lois-johnson@localhost Lois both none SocialStream
If we want to get all rosters (for example, to check if the database is synchronized correctly) :
admin@localhost:~/ejabberd_scripts$ ./emanagement printAllRosters
------------------------
Init Ejabberd Maintenance script
------------------------
-------------------------------------
jacqueline-moore Roster
-------------------------------------
pamela-hall@localhost Pamela both none SocialStream
-------------------------------------
-------------------------------------
pamela-hall Roster
-------------------------------------
jacqueline-moore@localhost Jacqueline both none SocialStream
demo@localhost Demo both none SocialStream
-------------------------------------
[...]
We can also check if a bidirecctional contact is reflected in the ejabberd database:
admin@localhost:~/ejabberd_scripts$ ./emanagement checkBidirecctionalBuddys demo@localhost pamela-hall@localhost
------------------------
Init Ejabberd Maintenance script
------------------------
true
Ejabberdctl provides commands to send xmpp stanzas, but command syntax, magic quotes and scaping special characters probably will be a headache.
Emanagement provides an interfaz to send stanzas in a very simple way, let's go with the examples:
Remember that to send a stanza as a user, the user needs to have an active session in the xmpp server.
//Send available presence stanza
admin@localhost:~/ejabberd_scripts$ ./emanagement setPresence demo
------------------------
Init Ejabberd Maintenance script
------------------------
Done
And the xmpp server info report:
=INFO REPORT==== 30-Nov-2011::17:43:09 ===
I(<0.665.0>:mod_sspresence:50) : mod_sspresence: on_presence ("demo")
=INFO REPORT==== 30-Nov-2011::17:43:09 ===
I(<0.665.0>:mod_sspresence:56) :
mod_sspresence: set_presence_script call with user ("demo") and status ("chat")
//Send presence stanza with status
admin@localhost:~/ejabberd_scripts$ ./emanagement sendPresence demo away
------------------------
Init Ejabberd Maintenance script
------------------------
demo
40461314681322670986499400
Done
And the xmpp server info report:
=INFO REPORT==== 30-Nov-2011::17:36:56 ===
I(<0.665.0>:mod_sspresence:56) :
mod_sspresence: set_presence_script call with user ("demo") and status ("away")
//Send presence stanza with status
admin@localhost:~/ejabberd_scripts$ ./emanagement sendMessageToUser SocialStream demo "Hello World"
------------------------
Init Ejabberd Maintenance script
------------------------
Done
That's all!
Coming soon...