modules/asterisk/INSTALL.txt

$Id: INSTALL.txt,v 1.20 2008/05/09 17:32:43 thehunmonkgroup Exp $

_Please_ read README.txt!

ON THE DRUPAL SERVER:

1.  Copy the entire 'asterisk' directory to your 'modules' directory,
    this will be either 'sites/all/modules' or 'sites/[yoursite]/modules'.

2.  Enable the module at Administer Site building -> Modules.  The database
    tables will be installed automatically. 

3.  Edit the settings for the module at Administer -> Asterisk integration ->
    Settings.  If you're setting up your own Asterisk server, you'll need to
    set the location of the Asterisk XML-RPC server and the Asterisk server
    password based upon the setup instructions below, otherwise obtain that
    information from the folks whose Asterisk server you're using.

    To test the connection to the Asterisk server, save your settings then
    click the 'Test connection' link.

4.  Add the 'make calls' permission to the roles that you wish to allow calling
    permissions. Add the 'upload recordings' permission to the roles that you
    wish to allow message recording permissions.  The permissions page is
    located  at Administer -> User management-> Permissions. 

      NOTE: A role must have both the 'make calls' and 'upload recordings'
            permission in order for message recording to be enabled for
            that role.

5.  To enable telephone recording capability for a particular node type, visit
    Administer -> Content management -> Content types, click on the content
    type, and check the 'Allow telephone recordings' checkbox.


TO TEST YOUR SETUP:

1.  Edit your user account and add your phone number (full digits for NANPA).

2.  Click on the 'call me' link under the 'Telephone' section on your user 
    account page.

Your Drupal site should call you and play the Asterisk demo!


SETTING UP YOUR OWN ASTERISK SERVER:

Before you get started, please understand that properly setting up an Asterisk
server can be a very difficult process if you have no previous experience.
These setup directions assume that you have already successfully set up 
Asterisk, and have some idea of how to make it work.  The author will provide
no support of any kind for the server side of this module--it's assumed that
you have the necessary skills to troubleshoot any issues that come up.

The module uses a customized version of Drupal's XML-RPC code to create an
XML-RPC server on the Asterisk server.  You'll need to make sure you have a
webserver that can execute PHP scripts properly configured on your asterisk
server.

This setup allows for Drupal to initiate the calls to Asterisk which offers a 
number of benefits:

  -- The calls happen in near real-time.
  -- No additional burden is placed on the Asterisk server to check the Drupal
     site for calls.
  -- If the asterisk webserver is set up securely, then all sensitive data will 
     be encrypted, even if the Drupal site is not a secure site.

NOTE: It is HIGHLY recommended to set up a secure webserver via SSL for this
XML-RPC server. The asterisk module is designed to always initiate any XML-RPC
calls to the Asterisk server when there could be sensitive data being
transmitted. If you do not have a security layer in place, usernames and
passwords could be intercepted, possibly allowing outsiders to place calls
through your Asterisk server! If you don't know how to set up a secure
webserver, there are many good tutorials to be found on the internet--acquaint
yourself... :)

The setup directions listed below assume that the Drupal installation and the
Asterisk installation are on different servers.  If they are on the same server
you'll need to adjust them accordingly.

1.  Copy xmlrpc.inc and xmlrpcs.inc from the 'includes' directory of your Drupal
    installation into the 'drupal_integration' directory of the asterisk module.

    NOTE: If/when you upgrade your asterisk module installation on the Asterisk
          server, you'll need to update these files!

2.  Move or copy the entire 'drupal_integration' and 'drupal_accounts'
    directories to your Asterisk server in a location of your choice.

      NOTE: Don't place 'drupal_accounts' anywhere inside 'drupal_integration'
            --this directory holds client data, and needs to be separate from
            the code directory for upgrade purposes.

3.  Move the 'asterisk_xmlrpc.php' file in the 'drupal_integration' directory
    to a publicly accessible place on your webserver.  The public address of
    this file is what Drupal sites will place in their asterisk module settings
    as the location of the Asterisk XML-RPC server.

4.  Create any initial account directories inside of the 'drupal_accounts'
		directory. View the README.txt in 'drupal_accounts' for details on how
		to do this.

5.  Set the ownership/permissions for the directories as follows:

    drupal_accounts and contents -- owner:group webserver user, 0770
    drupal_integration and contents -- owner:group webserver user:Asterisk user, 0750
    drupal_integration/conf and contents --  owner:group Asterisk user, 0700
    drupal_integration/scripts and contents -- owner:group Asterisk user, 0700
    drupal_integration/sounds and contents -- owner:group Asterisk user, 0700

    You'll also need to give the webserver user permission to write to the
    Asterisk call spool.  This might most easily be accomplished by setting
    the group of the call spool directory to the webserver group, and
    setting perms to 720.

    Another approach, if you're only using the webserver as the XML-RPC
    server outlined here, is to have the Asterisk user run the webserver.

    NOTE: The above file permissions steps are very important to the
          integrity of your system, please don't take them lightly!

6.  Edit the paths for the define statments at the top of the
    'asterisk_xmlrpc.php' and 'drupal_integration/scripts/AGI_conf.inc' files.
    For each, provide the full path to the 'drupal_integration' and
    'drupal_accounts' directories located on the Asterisk server.

7.  Check the important notes at the top of
    'drupal_integration/scripts/save_recording_message.agi', and make sure
    your current PHP setup will support the script.

8.  Edit the paths for the define statements in the
    'drupal_integration/asterisk_config.inc' file--the current settings are
    merely a best guess. Check the paths to each of the specified locations
    on your Asterisk server, and change if necessary.

9.  Add the following variables to the [globals] section of your Asterisk 
    dialplan.  The variable values must be the full paths to the
    drupal_integration and drupal_accounts directories respectively.

      DRUPAL_INTEGRATION = /full/path/to/drupal_integration
      DRUPAL_ACCOUNTS = /full/path/to/drupal_accounts

10. Add 'drupal_integration/conf/drupal-extensions.conf' to your Asterisk
    dialplan.

      #include /full/path/to/drupal_integration/conf/drupal-extensions.conf

      IMPORTANT: The '#' is NOT a comment indicator in extensions.conf

      NOTE: PSTN calling is disabled by default in drupal-extensions.conf--
            you'll need to enable and properly configure it--that's out of
            scope for this installation text!

11. Reload the extensions on your Asterisk server:

      extensions reload
1	$Id: INSTALL.txt,v 1.20 2008/05/09 17:32:43 thehunmonkgroup Exp $
2
3	_Please_ read README.txt!
4
5	ON THE DRUPAL SERVER:
6
7	1. Copy the entire 'asterisk' directory to your 'modules' directory,
8	this will be either 'sites/all/modules' or 'sites/[yoursite]/modules'.
9
10	2. Enable the module at Administer Site building -> Modules. The database
11	tables will be installed automatically.
12
13	3. Edit the settings for the module at Administer -> Asterisk integration ->
14	Settings. If you're setting up your own Asterisk server, you'll need to
15	set the location of the Asterisk XML-RPC server and the Asterisk server
16	password based upon the setup instructions below, otherwise obtain that
17	information from the folks whose Asterisk server you're using.
18
19	To test the connection to the Asterisk server, save your settings then
20	click the 'Test connection' link.
21
22	4. Add the 'make calls' permission to the roles that you wish to allow calling
23	permissions. Add the 'upload recordings' permission to the roles that you
24	wish to allow message recording permissions. The permissions page is
25	located at Administer -> User management-> Permissions.
26
27	NOTE: A role must have both the 'make calls' and 'upload recordings'
28	permission in order for message recording to be enabled for
29	that role.
30
31	5. To enable telephone recording capability for a particular node type, visit
32	Administer -> Content management -> Content types, click on the content
33	type, and check the 'Allow telephone recordings' checkbox.
34
35
36	TO TEST YOUR SETUP:
37
38	1. Edit your user account and add your phone number (full digits for NANPA).
39
40	2. Click on the 'call me' link under the 'Telephone' section on your user
41	account page.
42
43	Your Drupal site should call you and play the Asterisk demo!
44
45
46	SETTING UP YOUR OWN ASTERISK SERVER:
47
48	Before you get started, please understand that properly setting up an Asterisk
49	server can be a very difficult process if you have no previous experience.
50	These setup directions assume that you have already successfully set up
51	Asterisk, and have some idea of how to make it work. The author will provide
52	no support of any kind for the server side of this module--it's assumed that
53	you have the necessary skills to troubleshoot any issues that come up.
54
55	The module uses a customized version of Drupal's XML-RPC code to create an
56	XML-RPC server on the Asterisk server. You'll need to make sure you have a
57	webserver that can execute PHP scripts properly configured on your asterisk
58	server.
59
60	This setup allows for Drupal to initiate the calls to Asterisk which offers a
61	number of benefits:
62
63	-- The calls happen in near real-time.
64	-- No additional burden is placed on the Asterisk server to check the Drupal
65	site for calls.
66	-- If the asterisk webserver is set up securely, then all sensitive data will
67	be encrypted, even if the Drupal site is not a secure site.
68
69	NOTE: It is HIGHLY recommended to set up a secure webserver via SSL for this
70	XML-RPC server. The asterisk module is designed to always initiate any XML-RPC
71	calls to the Asterisk server when there could be sensitive data being
72	transmitted. If you do not have a security layer in place, usernames and
73	passwords could be intercepted, possibly allowing outsiders to place calls
74	through your Asterisk server! If you don't know how to set up a secure
75	webserver, there are many good tutorials to be found on the internet--acquaint
76	yourself... :)
77
78	The setup directions listed below assume that the Drupal installation and the
79	Asterisk installation are on different servers. If they are on the same server
80	you'll need to adjust them accordingly.
81
82	1. Copy xmlrpc.inc and xmlrpcs.inc from the 'includes' directory of your Drupal
83	installation into the 'drupal_integration' directory of the asterisk module.
84
85	NOTE: If/when you upgrade your asterisk module installation on the Asterisk
86	server, you'll need to update these files!
87
88	2. Move or copy the entire 'drupal_integration' and 'drupal_accounts'
89	directories to your Asterisk server in a location of your choice.
90
91	NOTE: Don't place 'drupal_accounts' anywhere inside 'drupal_integration'
92	--this directory holds client data, and needs to be separate from
93	the code directory for upgrade purposes.
94
95	3. Move the 'asterisk_xmlrpc.php' file in the 'drupal_integration' directory
96	to a publicly accessible place on your webserver. The public address of
97	this file is what Drupal sites will place in their asterisk module settings
98	as the location of the Asterisk XML-RPC server.
99
100	4. Create any initial account directories inside of the 'drupal_accounts'
101	directory. View the README.txt in 'drupal_accounts' for details on how
102	to do this.
103
104	5. Set the ownership/permissions for the directories as follows:
105
106	drupal_accounts and contents -- owner:group webserver user, 0770
107	drupal_integration and contents -- owner:group webserver user:Asterisk user, 0750
108	drupal_integration/conf and contents -- owner:group Asterisk user, 0700
109	drupal_integration/scripts and contents -- owner:group Asterisk user, 0700
110	drupal_integration/sounds and contents -- owner:group Asterisk user, 0700
111
112	You'll also need to give the webserver user permission to write to the
113	Asterisk call spool. This might most easily be accomplished by setting
114	the group of the call spool directory to the webserver group, and
115	setting perms to 720.
116
117	Another approach, if you're only using the webserver as the XML-RPC
118	server outlined here, is to have the Asterisk user run the webserver.
119
120	NOTE: The above file permissions steps are very important to the
121	integrity of your system, please don't take them lightly!
122
123	6. Edit the paths for the define statments at the top of the
124	'asterisk_xmlrpc.php' and 'drupal_integration/scripts/AGI_conf.inc' files.
125	For each, provide the full path to the 'drupal_integration' and
126	'drupal_accounts' directories located on the Asterisk server.
127
128	7. Check the important notes at the top of
129	'drupal_integration/scripts/save_recording_message.agi', and make sure
130	your current PHP setup will support the script.
131
132	8. Edit the paths for the define statements in the
133	'drupal_integration/asterisk_config.inc' file--the current settings are
134	merely a best guess. Check the paths to each of the specified locations
135	on your Asterisk server, and change if necessary.
136
137	9. Add the following variables to the [globals] section of your Asterisk
138	dialplan. The variable values must be the full paths to the
139	drupal_integration and drupal_accounts directories respectively.
140
141	DRUPAL_INTEGRATION = /full/path/to/drupal_integration
142	DRUPAL_ACCOUNTS = /full/path/to/drupal_accounts
143
144	10. Add 'drupal_integration/conf/drupal-extensions.conf' to your Asterisk
145	dialplan.
146
147	#include /full/path/to/drupal_integration/conf/drupal-extensions.conf
148
149	IMPORTANT: The '#' is NOT a comment indicator in extensions.conf
150
151	NOTE: PSTN calling is disabled by default in drupal-extensions.conf--
152	you'll need to enable and properly configure it--that's out of
153	scope for this installation text!
154
155	11. Reload the extensions on your Asterisk server:
156
157	extensions reload