Fix various documentation issues (bugs #5464-5467)

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@6826 f38db490-d61c-443f-a65b-d21fe96a405b

5 files changed, 153 insertions, 74 deletions

diff --git a/CREDITS b/CREDITS
index 5a2bc272c..fee5be6b3 100755
--- a/CREDITS
+++ b/CREDITS
@@ -1,6 +1,6 @@
 
 === DEVELOPMENT SUPPORT ===
-I'd like to thank the following companies for helping fund development of
+We'd like to thank the following companies for helping fund development of
 Asterisk:
 
 Pilosoft, Inc. - for supporting ADSI development in Asterisk
@@ -26,33 +26,36 @@ Wasim - Hangup detect
 PhoneJack and Linejack card to the project.  (http://www.quicknet.net)
 
 === MISCELLANEOUS PATCHES ===
+Jim Dixon - Zapata Telephony and app_rpt
+	http://www.zapatatelephony.org/app_rpt.html
 Russell Bryant - Asterisk 1.0 maintainer and misc. enhancements
-       russelb@clemson.edu
-Anthony Minessale - Countless big and small fixes, and relentless forward push
-       anthmct@yahoo.com              http://www.asterlink.com
+	russelb@clemson.edu
+Anthony Minessale II - Countless big and small fixes, and relentless forward push
+	anthmct@yahoo.com              http://www.asterlink.com
 James Golovich - Innumerable contributions
-       You can find him and asterisk-perl at http://asterisk.gnuinter.net
+	You can find him and asterisk-perl at http://asterisk.gnuinter.net
 Andre Bierwirth - Extension hints and status
 Oliver Daudey - ISDN4Linux fixes
 Pauline Middelink - ISDN4Linux patches and some general patches.
-       She can be found at http://www.polyware.nl/~middelink/En/
+	She can be found at http://www.polyware.nl/~middelink/En/
 Jean-Denis Girard - Various contributions from the South Pacific Islands
-       jd-girard@esoft.pf             http://www.esoft.pf
-William Jordan / Vonage - MySQL enhancmenets to Voicemail
+	jd-girard@esoft.pf             http://www.esoft.pf
+William Jordan / Vonage - MySQL enhancements to Voicemail
 	wjordan@vonage.com
 Jac Kersing - Various fixes
 Steven Critchfield - Seek and Trunc functions for playback and recording
-       critch@basesys.com
+	critch@basesys.com
 Jefferson Noxon - app_lookupcidname, app_db, and various other contributions
 Klaus-Peter Junghanns - in-band DTMF on SIP and MGCP
 Ross Finlayson - Dynamic RTP payload support
 Mahmut Fettahlioglu - Audio recording, music-on-hold changes, alaw file
-       format, and various fixes. Can be contacted at mahmut@oa.com.au
+	format, and various fixes. Can be contacted at mahmut@oa.com.au
 James Dennis - Cisco SIP compatibility patches to work with SIP service
-       providers. Can be contacted at asterisk@jdennis.net
-Tilghman Lesher - - Route lookup code; ast_localtime(), ast_say_date_with_format(); 
-                    GotoIfTime, Random, SayUnixTime, HasNewVoicemail, and Cut applications, 
-		    along with various other patches. http://asterisk.drunkcoder.com/
+	providers. Can be contacted at asterisk@jdennis.net
+Tilghman Lesher - ast_localtime(); ast_say_date_with_format(); 
+	GotoIfTime, Random, SayUnixTime, HasNewVoicemail applications;
+	CUT, SORT, EVAL, CURL, FIELDQTY, STRFTIME, QUEUEAGENT* functions;
+	and other innumerable bug fixes. http://asterisk.drunkcoder.com/
 Jayson Vantuyl - Manager protocol changes, various other bugs.
 	jvantuyl@computingedge.net
 Thorsten Lockert - OpenBSD, FreeBSD ports, making MacOS X port run on 10.3,
@@ -60,24 +63,31 @@ Thorsten Lockert - OpenBSD, FreeBSD ports, making MacOS X port run on 10.3,
 	bugs. tholo@sigmasoft.com
 Brian West - ODBC support and Bug Marshaling  
 Josh Roberson - chan_zap reload support, Advanced Voicemail Features, other misc. patches,
-		and Bug Marshalling. - josh@asteriasgi.com, http://www.asteriasgi.com
+	and Bug Marshalling. - josh@asteriasgi.com, http://www.asteriasgi.com
 William Waites - syslog support, SIP NAT traversal for SIP-UA. ww@styx.org
 Rich Murphey - Porting to FreeBSD, NetBSD, OpenBSD, and Darwin.
 	rich@whiteoaklabs.com  http://whiteoaklabs.com
 Simon Lockhart - Porting to Solaris (based on work of Logan ???)	
 	simon@slimey.org
-Olle Johansson - SIP RFC compliance and testing, testing, testing
-	oej@edvina.net
+Olle E. Johansson - SIP RFC compliance, documentation and testing, testing, testing
+	oej@edvina.net, http://edvina.net
+Steve Kann - new jitter buffer for IAX2
+	stevek@stevek.com
+Constantine Filin - major contributions to the Asterisk Realtime Architecture
+Steve Murphy - privacy support
 
 === OTHER CONTRIBUTIONS ===
 John Todd - Monkey sounds and associated teletorture prompt
+Michael Jerris - bug marshaling
+Leif Madsen, Jared Smith and Jim van Meggelen - the Asterisk book
+	available under a Creative Commons License at http://www.asteriskdocs.org
 
 === HOLD MUSIC ===
 Music provided by www.freeplaymusic.com
 
 === OTHER SOURCE CODE IN ASTERISK ===
 
-I did not implement the codecs in asterisk.  Here is the copyright on the
+Digium did not implement the codecs in Asterisk.  Here is the copyright on the
 GSM source:
 
 Copyright 1992, 1993, 1994 by Jutta Degener and Carsten Bormann,
@@ -102,7 +112,7 @@ And the copyright on the ADPCM source:
 Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam, The
 Netherlands.
 
-                        All Rights Reserved
+	                 All Rights Reserved
 
 Permission to use, copy, modify, and distribute this software and its
 documentation for any purpose and without fee is hereby granted,
diff --git a/SECURITY b/SECURITY
index b31fb17ab..3290cba48 100755
--- a/SECURITY
+++ b/SECURITY
@@ -4,6 +4,32 @@ PLEASE READ THE FOLLOWING IMPORTANT SECURITY RELATED INFORMATION.
 IMPROPER CONFIGURATION OF ASTERISK COULD ALLOW UNAUTHORIZED USE OF YOUR
 FACILITIES, POTENTIALLY INCURRING SUBSTANTIAL CHARGES.
 
+Asterisk security involves both network security (encryption, authentication)
+as well as dialplan security (authorization - who can access services in 
+your pbx). If you are setting up Asterisk in production use, please make
+sure you understand the issues involved.
+
+* NETWORK SECURITY
+
+If you install Asterisk and use the "make samples" command to install
+a demonstration configuration, Asterisk will open a few ports for accepting
+VoIP calls. Check the channel configuration files for the ports and IP addresses.
+
+If you enable the manager interface in manager.conf, please make sure that
+you access manager in a safe environment or protect it with SSH or other
+VPN solutions.
+
+For all TCP/IP connections in Asterisk, you can set ACL lists that
+will permit or deny network access to Asterisk services. Please check
+the "permit" and "deny" configuration options in manager.conf and
+the VoIP channel configurations - i.e. sip.conf and iax.conf.
+
+The IAX2 protocol supports strong RSA key authentication as well as
+AES encryption of voice and signalling. The SIP channel does not
+support encryption in this version of Asterisk.
+
+* DIALPLAN SECURITY
+
 First and foremost remember this:
 
 USE THE EXTENSION CONTEXTS TO ISOLATE OUTGOING OR TOLL SERVICES FROM ANY
@@ -38,4 +64,4 @@ exten => 6123,Dial(Zap/1)
 
 DON'T FORGET TO TAKE THE DEMO CONTEXT OUT OF YOUR DEFAULT CONTEXT.  There
 isn't really a security reason, it just will keep people from wanting to 
-play with your asterisk setup remotely.
+play with your Asterisk setup remotely.
diff --git a/asterisk.8 b/asterisk.8
index d03c7873e..6831d0fa8 100755
--- a/asterisk.8
+++ b/asterisk.8
@@ -3,7 +3,7 @@
 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
 .\" Please send any bug reports, improvements, comments, patches, 
 .\" etc. to Steve Cheng <steve@ggi-project.org>.
-.TH "ASTERISK" "8" "17 May 2005" "asterisk 1.0" ""
+.TH "ASTERISK" "8" "18 October 2005" "asterisk 1.2" ""
 
 .SH NAME
 asterisk \- All-purpose telephony server.
@@ -20,22 +20,25 @@ asterisk \- All-purpose telephony server.
 provides Private Branch eXchange (PBX), Interactive Voice Response (IVR),
 Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, 
 Conferencing, and a plethora of other telephony applications to a broad
-range of telephony devices including packet voice (SIP, IAX, MGCP, Skinny,
+range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny,
 H.323) devices (both endpoints and proxies), as well as traditional TDM
 hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart,
 ISDN BRI, and many more.
 .PP
-Asterisk reads most of its configuration files from configuration files
-located in /etc/asterisk.  Virtually all aspects of the operation of
-asterisk's configuration files can be found in the sample configuration
-files.  The format for those files is generally beyond the scope of this
-man page.
+At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration
+file and locates the rest of the configuration files from the configuration
+in that file. The -C option specifies an alternate main configuration file.
+Virtually all aspects of the operation of asterisk's configuration files
+can be found in the sample configuration files.  The format for those files
+is generally beyond the scope of this man page.
 .PP
 When running with \fB-c\fR, \fB-r\fR or \fB-R\fR
 options, Asterisk supplies a powerful command line, including command
 completion, which may be used to monitors its status, perform a variety
 of administrative actions and even explore the applications that are
 currently loaded into the system.
+.PP
+Asterisk is a trademark of Digium, Inc.
 .SH "OPTIONS"
 .TP
 \fB-C \fIfile\fB\fR
@@ -49,6 +52,10 @@ asterisk to no longer fork or detach from the controlling terminal.
 .TP
 \fB-d\fR
 Enable extra debugging statements.
+
+Note: This always sets the debug level in the asterisk process,
+even if it is running in the background. This will affect the size
+of your log files.
 .TP
 \fB-f\fR
 Do not fork or detach from controlling terminal.
@@ -70,7 +77,8 @@ socket, the asterisk database, etc.
 Provide brief summary of command line arguments and terminate.
 .TP
 \fB-i\fR
-Prompt user to intialize any encrypted private keys during startup.
+Prompt user to intialize any encrypted private keys for IAX2
+secure authentication during startup.
 .TP
 \fB-M \fIvalue\fB\fR
 Limits the maximum number of calls to the specified value.  This can
@@ -122,7 +130,11 @@ Increase the level of verboseness on the console.  The more times
 Specifying this option implies \fB-f\fR and will cause
 asterisk to no longer fork or detach from the controlling terminal.
 This option may also be used in conjunction with \fB-r\fR
-and \fB-R\fR
+and \fB-R\fR\&.
+
+Note: This always sets the verbose level in the asterisk process,
+even if it is running in the background. This will affect the size
+of your log files.
 .TP
 \fB-V\fR
 Display version information and exit immediately.
@@ -147,7 +159,9 @@ Bug reports and feature requests may be filed at http://bugs.digium.com
 .PP
 *CLI> \fBhelp\fR - Help on Asterisk CLI
 .PP
-*CLI> \fBshow applications\fR - Show loaded applications
+*CLI> \fBshow applications\fR - Show loaded dialplan applications
+.PP
+*CLI> \fBshow functions\fR - Show loaded dialplan functions
 .PP
 http://www.asterisk.org - The Asterisk Home Page
 .PP
diff --git a/asterisk.sgml b/asterisk.sgml
index abee2e678..c29b4af30 100755
--- a/asterisk.sgml
+++ b/asterisk.sgml
@@ -1,14 +1,14 @@
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
 <refentry>
 <refentryinfo>
-	<date>2004-07-18</date>
+	<date>2005-10-18</date>
 </refentryinfo>
 <refmeta>
 	<refentrytitle>
 		<application>asterisk</application>
 	</refentrytitle>
 	<manvolnum>8</manvolnum>
-	<refmiscinfo>asterisk 1.0</refmiscinfo>
+	<refmiscinfo>asterisk 1.2</refmiscinfo>
 </refmeta>
 <refnamediv>
 	<refname>
@@ -45,17 +45,18 @@
 	provides Private Branch eXchange (PBX), Interactive Voice Response (IVR),
 	Automated Call Distribution (ACD), Voice over IP (VoIP) gatewaying, 
 	Conferencing, and a plethora of other telephony applications to a broad
-	range of telephony devices including packet voice (SIP, IAX, MGCP, Skinny,
+	range of telephony devices including packet voice (SIP, IAX2, MGCP, Skinny,
 	H.323) devices (both endpoints and proxies), as well as traditional TDM
 	hardware including T1, E1, ISDN PRI, GR-303, RBS, Loopstart, Groundstart,
 	ISDN BRI, and many more.
 	</para>
 	<para>
-	Asterisk reads most of its configuration files from configuration files
-	located in /etc/asterisk.  Virtually all aspects of the operation of
-	asterisk's configuration files can be found in the sample configuration
-	files.  The format for those files is generally beyond the scope of this
-	man page.
+	At start, Asterisk reads the /etc/asterisk/asterisk.conf main configuration
+	file and locates the rest of the configuration files from the configuration
+	in that file. The -C option specifies an alternate main configuration file.
+	Virtually all aspects of the operation of asterisk's configuration files
+	can be found in the sample configuration files.  The format for those files
+	is generally beyond the scope of this man page.
 	</para>
 	<para>
 	When running with <command>-c</command>, <command>-r</command> or <command>-R</command>
@@ -64,6 +65,9 @@
 	of administrative actions and even explore the applications that are
 	currently loaded into the system.
 	</para>
+	<para>
+	Asterisk is a trademark of Digium, Inc.
+	</para>
 </refsect1>
 <refsect1>
 	<title>OPTIONS</title>
@@ -93,6 +97,11 @@
 			<para>
 			Enable extra debugging statements.
 			</para>
+			<para>
+			Note: This always sets the debug level in the asterisk process,
+			even if it is running in the background. This will affect the size
+			of your log files.
+			</para>
 		</listitem>
 	</varlistentry>
 	<varlistentry>
@@ -138,7 +147,8 @@
 		<term>-i</term>
 		<listitem>
 			<para>
-			Prompt user to intialize any encrypted private keys during startup.
+			Prompt user to intialize any encrypted private keys for IAX2
+			secure authentication during startup.
 			</para>
 		</listitem>
 	</varlistentry>
@@ -240,7 +250,12 @@
 			Specifying this option implies <command>-f</command> and will cause
 			asterisk to no longer fork or detach from the controlling terminal.
 			This option may also be used in conjunction with <command>-r</command>
-			and <command>-R</command>
+			and <command>-R</command>.
+			</para>
+			<para>
+			Note: This always sets the verbose level in the asterisk process,
+			even if it is running in the background. This will affect the size
+			of your log files.
 			</para>
 		</listitem>
 	</varlistentry>
@@ -290,7 +305,10 @@
 	*CLI&gt; <command>help</command> - Help on Asterisk CLI
 	</para>
 	<para>
-	*CLI&gt; <command>show applications</command> - Show loaded applications
+	*CLI&gt; <command>show applications</command> - Show loaded dialplan applications
+	</para>
+	<para>
+	*CLI&gt; <command>show functions</command> - Show loaded dialplan functions
 	</para>
 	<para>
 	http://www.asterisk.org - The Asterisk Home Page
diff --git a/doc/README.sms b/doc/README.sms
index f4b75a84e..02e38764b 100755
--- a/doc/README.sms
+++ b/doc/README.sms
@@ -1,28 +1,39 @@
-SMS() is an application to handles calls to/from text message capable phones and message centres using ETSI ES 201 912 protocol 1 FSK messaging over analogue calls.
+* The SMS application
+---------------------
+SMS() is an application to handles calls to/from text message capable phones and 
+message centres using ETSI ES 201 912 protocol 1 FSK messaging over analog calls.
 
-Basically it allows sending and receiving of text messages over the PSTN. It is compatible with BT Text service in the UK and works on ISDN and PSTN lines. It is designed to connect to an ISDN or zap interface directly and uses FSK so would probably not work over any sort of compressed link.
+Basically it allows sending and receiving of text messages over the PSTN. It is 
+compatible with BT Text service in the UK and works on ISDN and PSTN lines. It is 
+designed to connect to an ISDN or zap interface directly and uses FSK so would 
+probably not work over any sort of compressed link (like a VoIP call using GSM codec).
 
 Typical applications include:-
 
-1. Connection to a message centre to send text messages - probably initiated via the manager interface or "outgoing" directory
-2. Connection to an POTS line with an SMS capable phone to send messages - probably initiated via the manager interface or "Outgoing" directory
-3. Acceptance of calls from the message centre (based on CLI) and storage of received messages
-4. Acceptance of calls from a POTS line with an SMS capable phone and storage of received messages
+1. Connection to a message centre to send text messages - probably initiated via the 
+   manager interface or "outgoing" directory
+2. Connection to an POTS line with an SMS capable phone to send messages - probably
+   initiated via the manager interface or "outgoing" directory
+3. Acceptance of calls from the message centre (based on CLI) and storage of 
+   received messages
+4. Acceptance of calls from a POTS line with an SMS capable phone and storage of
+   received messages
 
-First argument is queue name
-
-Second is options
+* Arguments to sms():
 
+- First argument is queue name
+- Second is options:
  a: SMS() is to act as the answering side, and so send the initial FSK frame
  s: SMS() is to act as a service centre side rather than as terminal equipment
 
-If a third argument is specified, then SMS does not handle the call at all,
-but takes the third argument as a destination number to send an SMS to, and
-the forth argument onward as a message to be queued. All this does is create
-the file in the me-sc directory. If 's' is set then the number is the source
-address and the message placed in the sc-me directory.
+- If a third argument is specified, then SMS does not handle the call at all,
+  but takes the third argument as a destination number to send an SMS to
+- The forth argument onward is a message to be queued to the number in the
+  third argument. All this does is create the file in the me-sc directory.
+  If 's' is set then the number is the source
+  address and the message placed in the sc-me directory.
 
-All text messages are in /var/spool/asterisk/sms
+All text messages are stored in /var/spool/asterisk/sms
 A log is recorded in /var/log/asterisk/sms
 
 There are two subdirectories called sc-me.<queuename> holding all
@@ -43,7 +54,7 @@ this mode are placed in the sc-me-<queuename> directory.
 Message files created by SMS() use a time stamp/reference based filename.
 
 The format of the sms file is lines that have the form of key=value
-Keys are :-
+Keys are :
 
 oa	Originating Address
 	Telephone number, national number if just digits
@@ -84,20 +95,21 @@ service.
 
 This is a context to use with a manager script.
 
-[smsdial]       ; create and send a text message, expects number+message and
-connect to 17094009
-exten = _X.,1,SMS(${CALLERIDNUM},,${EXTEN},${CALLERIDNAME})
-exten = _X.,2,SMS(${CALLERIDNUM})
-exten = _X.,3,Hangup
+[smsdial]
+; create and send a text message, expects number+message and
+; connect to 17094009
+exten => _X.,1,SMS(${CALLERIDNUM},,${EXTEN},${CALLERIDNAME})
+exten => _X.,n,SMS(${CALLERIDNUM})
+exten => _X.,n,Hangup
 
 The script sends
 
-action: originate
-callerid: message <from>
-exten: to
-channel: Local/17094009
-context: smsdial
-priority: 1
+	action: originate
+	callerid: message <from>
+	exten: to
+	channel: Local/17094009
+	context: smsdial
+	priority: 1
 
 You put the message as the name of the caller ID (messy, I know), the
 originating number and hence queue name as the number of the caller ID and the
@@ -113,12 +125,11 @@ by BT).
 For incoming calls you can use a context like this :-
 
 [incoming]
-exten = _XXXXXX/_8005875290,1,SMS(${EXTEN:3},a)
-exten = _XXXXXX/_8005875290,2,System(/usr/lib/asterisk/smsin ${EXTEN:3})
-exten = _XXXXXX/_80058752[0-8]0,1,SMS(${EXTEN:3}${CALLERIDNUM:8:1},a)
-exten = _XXXXXX/_80058752[0-8]0,2,System(/usr/lib/asterisk/smsin
-${EXTEN:3}${CALLERIDNUM:8:1})
-exten = _XXXXXX/_80058752X0,3,Hangup
+exten => _XXXXXX/_8005875290,1,SMS(${EXTEN:3},a)
+exten => _XXXXXX/_8005875290,n,System(/usr/lib/asterisk/smsin ${EXTEN:3})
+exten => _XXXXXX/_80058752[0-8]0,1,SMS(${EXTEN:3}${CALLERIDNUM:8:1},a)
+exten => _XXXXXX/_80058752[0-8]0,n,System(/usr/lib/asterisk/smsin ${EXTEN>:3}${CALLERIDNUM:8:1})
+exten => _XXXXXX/_80058752[0-8]0,n,Hangup
 
 
 In this case the called number we get from BT is 6 digits (XXXXXX) and we are