		Copyright (C) 2005-2011 Earl C. Terwilliger 
                   Version 2.0  Released 1/12/2011

This is the documentation file for the Asterisk WEB/PHP Management Interface.
These files are provided under the GNU license. A copy is supplied in the file
called COPYING.

To install, copy the tar file to the 'root' directory of your web server.
Then:

	tar -xzvf astwebmgr.tar.gz

it will create and install in a directory called 'asterisk'. You might need to run
chmod to allow the web server (apache) to write to this directory if you use all
the features of astwebmgr. (For example, the agi command obtains the agi documentation
writes it to the /asterisk directory, then displays it.)

Run something like this (assuming your web root is /var/www/html) to allow apache
write access to the asterisk directory:

cd /var/www/html
chown -R root.apache asterisk
chmod -R 754 asterisk

(Make sure to change the owner,group and permissions to values appropriate to your system
and your systems security needs.)

You can then invoke astwebmgr via:

	http://yourwebserver/asterisk

(Alternatively, place it in any directory of your choosing. The un tar command will
create the asterisk sub-directory from wherever you untar it. Then change the ownership and
permissions accordingly.)

All of the .php scripts have a brief description of there use in comments at the top
of each script. Here is a brief description of the provided files.

This file can be copied to the web 'root' and used as the 'favorite icon':
	
	favicon.ico

The file called parseconf.php is included but is  not directly accessable by the 
menuing interface. It is around just for 'debugging' purposes.

Should you need to customize any of the file names or functions, look 
at these two files:

	files.php
	functions.php

The files.php contains all the file names and directories. They are basically
the defaults but you can change them to match your installation.

To interface with the Asterisk Manager a login userid and password is necessary.
You will need to supply that in the /etc/asterisk/manager.conf file. See that
file for more specific information. The login.php script will parse that file
for the info it needs to login. No further customization is needed.
(Note: this is assuming that the web server where this is running from is the
same server where Asterisk is running.) Although.. the parsing function just
grabs the 1st userid and permissions so if that is not what you want you may
have to fix the login.php to get the id you specifically want. You can also
just customize it for a different Asterisk server than what the web server
is running on (however if you do this then most of the functionality is lost 
as only the manager interface will work.)

The main menu is the index.php file. The header.php file is 'included' from most 
all of the rest of the PHP scripts. It has the commands to invoke from the 
Java script menu system. (Edit and change the header.php file, if you want to 
change the commands in the drop down JavaScript menus.)

The index.php page includes the header.php file and also shows a table of the
available commands. The header.php script is the real menuing system which 
invokes the Java script menu and other .php scripts.

To invoke asterisk and other authorized commands, sudo is used.
Make sure to edit /etc/sudoers accordingly, and add entries like:

  apache   ALL = NOPASSWD: /usr/sbin/asterisk
  apache   ALL = NOPASSWD: /sbin/tc

or instead adding the command:
  
  apache ALL = NOPASSWD: ALL

will work too but is very insecure. Look at the functions.php script to see how
external programs are invoked and you can easily change the functions there to
match your security needs. 

To allow ASTWEBMGR to edit the Asterisk configuration files you will need to set up
correct permissions on the directories. Something like:

cd /etc
chown -R root.apache asterisk
chmod -R 664 asterisk
chmod 774 asterisk

cd /var/lib/asterisk
chown -R root.apache agi-bin
chmod -R 775 agi-bin
chmod 775 agi-bin

and the same for other directories that you might want to edit.

The images directory contains the few graphic images/logos used by this package.

The cgi-bin directory contains the Digium Supplied cgi-bin file to access voicemail
via the web. When you access this thru the web interface it will automatically be
copied to your web servers cgi-bin directory as specified in the files.php script.

The obtain directory shows how to obtain the latest version of this package.

These directories contain the files necessary to run the freely 
available JSCookMenu system:

	style
	theme
	java

More information about the JSCookMenu can be found here:
	
	http://www.cs.ucla.edu/~heng/JSCookMenu/


The functionality of these scripts should be obvious by trying them out.
The less obvious functionality comes in the Manager functions. When you click on
the Manager function it will display a menu of Manager Commands. If you click a
radio button then you must supply optional or required commands. Note: Some
commands do require parameters and some do not. Optionally you can click the link
to the command and it will prompt you for required commands.

If you hover the mouse over the Manager command, the Java script will display a 
drop down menu of several commonly used commands which require no parameters. One
of them is the List Help command. If you select the List Help command it will 
display a list of all of the available CLI (command line interface) commands.
Note that they are displayed as links which you can click on to easily run that
command. The Show Applications Command also displays the Applications as links which
when clicked run the help application command to get further help on that application. 

Edit and change the header.php file, if you want to change the mangager
commands or any of the commands in the drop down JavaScript menus.

The firewall function and the TC (traffic control or traffic shaping) functions
are included for testing and will not survive on machine re-boot. These functions
are perhaps better done via a script at boot time but are included here to allow
testing / experimenting thru a web interface. (These functions may or may not work
well with any other existing TC or firewall options already in effect.)

The MySQL administration function is a WEB interface to see databases, tables, etc. 
in table formatted output. It also allows any SQL query. Examples are supplied on
the 1st menu. When 1st invoked it prompts for the MySQL userid and password which
it saves in session variables. This function allows easy access to the CDR database,
for example, if your Asterisk installation uses it. It is a small but powerfull php
script usefull to manage MySQL even for databases used outside of Asterisk.

The scripts directory has several scripts which can be invoked from the top main
menu bar. ASTERKILL will kill all asterisk and mpg123 processes. ASTERSTART will run
in daemon mode and start/restart Asterisk automatically. Note: asterstart.py is now
a replacement for ASTERSTART.

The originate function has a menu item which parses the SIP.CONF file
(ASTSIPFILE variable) and makes buttons to allow easy push button dialing.

Starting with version 1.9, ASTWEBMGR now has code to dynamically inquire Asterisk
about what commands are available. ASTWEBMGR then builds the menus accordingly.


The author (Earl) can be reached at: earl@micpc.com if you have any questions.

VERSION HISTORY

2005      	Version < 1.4 		testing 
11-11-2005	Version   1.4		Initial version out to the public
11-13-2005	Version   1.4.1		changes to the README file (security concerns)
12-02-2005	Version   1.5		Added MySQL Administration
12-07-2005	Version   1.5.1		changes to header.php (built in commands)
04-15-2006	Version   1.5.2		changes to header.php (built in commands)
					changes to cmdexec.php (more help on applications)
                                        changes to files.php (added $ASTERSTART,$ASTERKILL)
					added scripts directory + commands ASTERSTART,ASTERKILL
04-18-2006	Version   1.5.3		changes to header.php (built in commands)
					added  sysfork.php for scripts to run correctly    
					changes to ASTERSTART    
04-19-2006	Version   1.5.4.1	changes to originate.php to fix DIAL files
					changes to files.php to include ASTSIPFILE    
					changes to header.php new Originate functions
					added placecall.php callselect.php for button dialing
04-19-2006	Version   1.5.5  	changes to callselect.php to fix button dialing
					added events.php to watch events
05-03-2006	Version   1.5.6  	changes to originate.php to fix call files
                                        changes to files.php to add tmpdir
					changes to cmdprompt.php to fix $_POST variables
05-12-2006	Version   1.5.7  	changes to db.php to add caller id name/number form
05-14-2006	Version   1.5.8  	changes to cdr.php added nowrap to table columns 
05-15-2006	Version   1.5.9  	changes to cmdexec.php added listcommands help
05-25-2006	Version   1.6    	changes to events.php  added set_time_limit
                                        changes to scripts/asterstart.c asterkill.sh   
                                        changes to style/style.css, callselect.php
06-20-2006	Version	  1.6.1		changes to callselect.php
                                        added asterstart.py to replace asterstart(.c)
11-15-2006      Version   1.7		added WANROUTER commands
11-22-2006      Version   1.8		added mgr.php, new astwebmgr logo
					cgi commands cdr_rpt.py,event_rpt.py
                                        updated scripts/asterstart.py
12-14-2006      Version   1.8.1		updated scripts/asterstart/py
01-03-2007      Version   1.9   	updated header.php
					added java/cmds.php and java/help.php 
12-20-2007      Version   1.9.1		updated callselect.php to fix SIP.CONF
					  parsing
					replace asterstart.py with updated version
1-12-2011	Version	  2.0		updated to run with Asterisk 1.8
1-15-2011	Version	  2.1		changes to cmdexec.php          
