diff options
Diffstat (limited to 'doc/distributed_devstate-XMPP.txt')
| -rw-r--r-- | doc/distributed_devstate-XMPP.txt | 433 |
1 files changed, 0 insertions, 433 deletions
diff --git a/doc/distributed_devstate-XMPP.txt b/doc/distributed_devstate-XMPP.txt deleted file mode 100644 index 1a8c143b4..000000000 --- a/doc/distributed_devstate-XMPP.txt +++ /dev/null @@ -1,433 +0,0 @@ -=============================================================================== -=== -=== XMPP PubSub Distributed Device State -=== -=== Copyright (C) 2010, Digium, Inc. -=== Leif Madsen <lmadsen@digium.com> -=== -=============================================================================== - -------------------------------------------------------------------------------- ---- INTRODUCTION -------------------------------------------------------------------------------- - -This document describes installing and utilizing XMPP PubSub events to -distribute device state and message waiting indication (MWI) events between -servers. The difference between this method and OpenAIS (see -distributed_devstate.txt) is that OpenAIS can only be used in low latency -networks; meaning only on the LAN, and not across the internet. - -If you plan on distributing device state or MWI across the internet, then you -will require the use of XMPP PubSub events. - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Tigase Installation -------------------------------------------------------------------------------- - --- Description -- - -Currently the only server supported for XMPP PubSub events is the Tigase open -source XMPP/Jabber environment. This is the server that the various Asterisk -servers will connect to in order to distribute the events. The Tigase server can -even be clustered in order to provide high availability for your device state; -however, that is beyond the scope of this document. - -For more information about Tigase, visit their web site: - - http://www.tigase.org - --- Download -- - -To download the Tigase environment, get the latest version at: - - http://www.tigase.org/en/filebrowser/tigase-server - --- Install -- - -The Tigase server requires a working Java environment, including both a JRE -(Java Runtime Environment) and a JDK (Java Development Kit), currently at least -version 1.6. - -For more information about how to install Tigase, see the web site: - - http://www.tigase.org/en/content/quick-start - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Tigase Configuration -------------------------------------------------------------------------------- - -While installing Tigase, be sure you enable the PubSub module. Without it, the -PubSub events won't be accepted by the server, and your device state will not be -distributed. - -There are a couple of things you need to configure in Tigase before you start it -in order for Asterisk to connect. The first thing we need to do is generate the -self-signed certificate. To do this we use the keytool application. More -information can be found here: - - http://www.tigase.org/en/content/server-certificate - --- Generating the keystore file -- - -Generally, we need to run the following commands to generate a new keystore -file. - -# cd /opt/Tigase-4.3.1-b1858/certs - -Be sure to change the 'yourdomain' to your domain. - -# keytool -genkey -alias yourdomain -keystore rsa-keystore \ - -keyalg RSA -sigalg MD5withRSA - -The keytool application will then ask you for a password. Use the password -'keystore' as this is the default password that Tigase will use to load the -keystore file. - -You then need to specify your domain as the first value to be entered in the -security certificate. - -What is your first and last name? - [Unknown]: asterisk.mydomain.tld -What is the name of your organizational unit? - [Unknown]: -What is the name of your organization? - [Unknown]: -What is the name of your City or Locality? - [Unknown]: -What is the name of your State or Province? - [Unknown]: -What is the two-letter country code for this unit? - [Unknown]: -Is CN=asterisk.mydomain.tld, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct? - [no]: yes - -You will then be asked for another password, in which case you must just press -enter for the same password as Tigase will not work without them being the same. - -Enter key password for <mykey> - (RETURN if same as keystore password): - - --- Configuring init.properties -- - -The next step is to configure the init.properties file which is used by Tigase -to generate the tigase.xml file. Whenever you change the init.properties file -because sure to remove the current tigase.xml file so that it will be -regenerated at start up. - -# cd /opt/Tigase-4.3.1-b1858/etc - -Then edit the init.properties file and add the following: - -config-type=--gen-config-def ---admins=admin@asterisk.mydomain.tld ---virt-hosts=asterisk.mydomain.tld ---debug=server ---user-db=derby ---user-db-uri=jdbc:derby:/opt/Tigase-4.3.1-b1858 ---comp-name-1=pubsub ---comp-class-1=tigase.pubsub.PubSubComponent - -Be sure to change the domain in the --admin and --virt-hosts options. The most -important lines are --comp-name-1 and --comp-class-1 which tell Tigase to load -the PubSub module. - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Running Tigase -------------------------------------------------------------------------------- - -You can then start the Tigase server with the tigase.sh script. - -# cd /opt/Tigase-4.3.1-b1858 -# ./scripts/tigase.sh start etc/tigase.conf - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Adding Buddies to Tigase -------------------------------------------------------------------------------- - -At this time, Asterisk is not able to automatically register your peers for you, -so you'll need to use an external application to do the initial registration. - -Pidgin is an excellent multi-protocol instant messenger application which -supports XMPP. It runs on Linux, Windows, and OSX, and is open source. You can -get Pidgin from http://www.pidgin.im - -Then add the two buddies we'll use in Asterisk with Pidgin by connecting to -the Tigase server. For more information about how to register new buddies, see -the Pidgin documentation. - -Once the initial registration is done and loaded into Tigase, you no longer need -to worry about using Pidgin. Asterisk will then be able to load the peers into -memory at start up. - -The example peers we've used in the following documentation for our two nodes -are: - -server1@asterisk.mydomain.tld/astvoip1 -server2@asterisk.mydomain.tld/astvoip2 - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Installing Asterisk -------------------------------------------------------------------------------- - -Install Asterisk as usual. However, you'll need to make sure you have the -res_jabber module compiled, which requires the iksemel development library. -Additionally, be sure you have the OpenSSL development library installed so you -can connect securly to the Tigase server. - -Make sure you check menuselect that res_jabber is selected so that it will -compile. - -# cd asterisk-source -# ./configure - -# make menuselect - ---> Resource Modules - -If you don't have jabber.conf in your existing configuration, because sure to -copy the sample configuration file there. - -# cd configs -# cp jabber.conf.sample /etc/asterisk/jabber.conf - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Configuring Asterisk -------------------------------------------------------------------------------- - -We then need to configure our servers to communicate with the Tigase server. We -need to modify the jabber.conf file on the servers. The configurations below are -for a 2 server setup, but could be expanded for additional servers easily. - -The key note here is to note that the pubsub_node option needs to start with -pubsub, so for example, pubsub.asterisk.mydomain.tld. Without the 'pubsub' your -Asterisk system will not be able to distribute events. - -Additionally, you will need to specify each of the servers you need to connec to -using the 'buddy' option. - - --- Asterisk Server 1 -- - -[general] -debug=no ;;Turn on debugging by default. -;autoprune=yes ;;Auto remove users from buddy list. Depending on your - ;;setup (ie, using your personal Gtalk account for a test) - ;;you might lose your contacts list. Default is 'no'. -autoregister=yes ;;Auto register users from buddy list. -;collection_nodes=yes ;;Enable support for XEP-0248 for use with - ;;distributed device state. Default is 'no'. -;pubsub_autocreate=yes ;;Whether or not the PubSub server supports/is using - ;;auto-create for nodes. If it is, we have to - ;;explicitly pre-create nodes before publishing them. - ;;Default is 'no'. - -[asterisk] -type=client -serverhost=asterisk.mydomain.tld -pubsub_node=pubsub.asterisk.mydomain.tld -username=server1@asterisk.mydomain.tld/astvoip1 -secret=welcome -distribute_events=yes -status=available -usetls=no -usesasl=yes -buddy=server2@asterisk.mydomain.tld/astvoip2 - - --- Asterisk Server 2 -- - -[general] -debug=yes ;;Turn on debugging by default. -;autoprune=yes ;;Auto remove users from buddy list. Depending on your - ;;setup (ie, using your personal Gtalk account for a test) - ;;you might lose your contacts list. Default is 'no'. -autoregister=yes ;;Auto register users from buddy list. -;collection_nodes=yes ;;Enable support for XEP-0248 for use with - ;;distributed device state. Default is 'no'. -;pubsub_autocreate=yes ;;Whether or not the PubSub server supports/is using - ;;auto-create for nodes. If it is, we have to - ;;explicitly pre-create nodes before publishing them. - ;;Default is 'no'. - -[asterisk] -type=client -serverhost=asterisk.mydomain.tld -pubsub_node=pubsub.asterisk.mydomain.tld -username=server2@asterisk.mydomain.tld/astvoip2 -secret=welcome -distribute_events=yes -status=available -usetls=no -usesasl=yes -buddy=server1@asterisk.mydomain.tld/astvoip1 - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Basic Testing of Asterisk with XMPP PubSub -------------------------------------------------------------------------------- - -Once you have Asterisk installed with XMPP PubSub, it is time to test it out. - -We need to start up our first server and make sure we get connected to the XMPP -server. We can verify this with an Asterisk console command to determine if -we're connected. - -On Asterisk 1 we can run 'jabber show connected' to verify we're connected to -the XMPP server. - -*CLI> jabber show connected -Jabber Users and their status: - User: server1@asterisk.mydomain.tld/astvoip1 - Connected ----- - Number of users: 1 - -The command above has given us output which verifies we've connected our first -server. - -We can then check the state of our buddies with the 'jabber show buddies' CLI -command. - -*CLI> jabber show buddies -Jabber buddy lists -Client: server1@asterisk.mydomain.tld/astvoip1 - Buddy: server2@asterisk.mydomain.tld - Resource: None - Buddy: server2@asterisk.mydomain.tld/astvoip2 - Resource: None - -The output above tells us we're not connected to any buddies, and thus we're not -distributing state to anyone (or getting it from anyone). That makes sense since -we haven't yet started our other server. - -Now, let's start the other server and verify the servers are able to establish -a connection between each other. - -On Asterisk 2, again we run the 'jabber show connected' command to make sure -we've connected successfully to the XMPP server. - -*CLI> jabber show connected -Jabber Users and their status: - User: server2@asterisk.mydomain.tld/astvoip2 - Connected ----- - Number of users: 1 - -And now we can check the status of our buddies. - -*CLI> jabber show buddies -Jabber buddy lists -Client: server2@scooter/astvoip2 - Buddy: server1@asterisk.mydomain.tld - Resource: astvoip1 - node: http://www.asterisk.org/xmpp/client/caps - version: asterisk-xmpp - Jingle capable: yes - Status: 1 - Priority: 0 - Buddy: server1@asterisk.mydomain.tld/astvoip1 - Resource: None - -Excellent! So we're connected to the buddy on Asterisk 1, and we could run the -same command on Asterisk 1 to verify the buddy on Asterisk 2 is seen. - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Testing Distributed Device State -------------------------------------------------------------------------------- - -The easiest way to test distributed device state is to use the DEVICE_STATE() -diaplan function. For example, you could have the following piece of dialplan -on every server: - -[devstate_test] - -exten => 1234,hint,Custom:mystate - -exten => set_inuse,1,Set(DEVICE_STATE(Custom:mystate)=INUSE) -exten => set_not_inuse,1,Set(DEVICE_STATE(Custom:mystate)=NOT_INUSE) - -exten => check,1,NoOp(Custom:mystate is ${DEVICE_STATE(Custom:mystate)}) - - -Now, you can test that the cluster-wide state of "Custom:mystate" is what -you would expect after going to the CLI of each server and adjusting the state. - -server1*CLI> console dial set_inuse@devstate_test - ... - -server2*CLI> console dial check@devstate_test - -- Executing [check@devstate_test:1] NoOp("OSS/dsp", "Custom:mystate is INUSE") in new stack - -Various combinations of setting and checking the state on different servers can -be used to verify that it works as expected. Also, you can see the status of -the hint on each server, as well, to see how extension state would reflect the -state change with distributed device state: - -server2*CLI> core show hints - -= Registered Asterisk Dial Plan Hints =- - 1234@devstate_test : Custom:mystate State:InUse Watchers 0 - - -One other helpful thing here during testing and debugging is to enable debug -logging. To do so, enable debug on the console in /etc/asterisk/logger.conf. -Also, enable debug at the Asterisk CLI. - -*CLI> core set debug 1 - -When you have this debug enabled, you will see output during the processing of -every device state change. The important thing to look for is where the known -state of the device for each server is added together to determine the overall -state. - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Notes On Large Installations -------------------------------------------------------------------------------- - -On larger installations where you want a fully meshed network of buddies (i.e. -all servers have all the buddies of the remote servers), you may want some -method of distributing those buddies automatically so you don't need to modify -all servers (N+1) every time you add a new server to the cluster. - -The problem there is that you're confined by what's allowed in XEP-0060, and -unfortunately that means modifying affiliations by individual JID (as opposed to -the various subscription access models, which are more flexible). - -See here for details: -http://xmpp.org/extensions/xep-0060.html#owner-affiliations - -One method for making this slightly easier is to utilize the #exec functionality -in configuration files, and dynamically generate the buddies via script that -pulls the information from a database, or to #include a file which is -automatically generated on all the servers when you add a new node to the -cluster. - -Unfortunately this still requires a reload of res_jabber.so on all the servers, -but this could also be solved through the use of the Asterisk Manager Interface -(AMI). - -So while this is not the ideal situation, it is programmatically solvable with -existing technologies and features found in Asterisk today. - -------------------------------------------------------------------------------- - -------------------------------------------------------------------------------- ---- Questions, Comments, and Bug Reports -------------------------------------------------------------------------------- - -Please utilize the Asterisk issue tracker for all bug reports at -https://issues.asterisk.org |