From df1a340774efc74f80ab4d99fb01da958d3f18e2 Mon Sep 17 00:00:00 2001
From: Russell Bryant <russell@russellbryant.com>
Date: Mon, 2 Jul 2007 22:27:46 +0000
Subject: * Move LaTeX docs into a tex/ subdirectory of the doc/ dir * Add a
 Makefile in doc/tex/ for generating PDF and HTML * Add a README.txt file to
 doc/tex/ to document which tools are used and what   web sites to visit for
 getting them. * Update build_tools/prep_tarball to put the proper Asterisk
 version string   in the automatically generated PDF for release tarballs

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@72982 65c4cc65-6c06-0410-ace0-fbb531ad65f3
---
 doc/tex/configuration.tex | 198 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 198 insertions(+)
 create mode 100644 doc/tex/configuration.tex

(limited to 'doc/tex/configuration.tex')

diff --git a/doc/tex/configuration.tex b/doc/tex/configuration.tex
new file mode 100644
index 000000000..a501928bb
--- /dev/null
+++ b/doc/tex/configuration.tex
@@ -0,0 +1,198 @@
+\subsubsection{Introduction}
+
+The Asterisk configuration parser in the 1.2 version
+and beyond series has been improved in a number of ways. In
+addition to the realtime architecture, we now have the ability to create
+templates in configuration files, and use these as templates when we
+configure phones, voicemail accounts and queues.
+
+These changes are general to the configuration parser, and works in
+all configuration files. 
+
+\subsubsection{General syntax}
+Asterisk configuration files are defined as follows:
+
+\begin{verbatim}
+	[section]
+	label = value
+	label2 = value
+\end{verbatim}
+
+In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax
+is a bit different. In these files the syntax is as follows:
+	
+\begin{verbatim}
+	[section]
+	label1 = value1
+	label2 = value2
+	object => name
+
+	label3 = value3
+	label2 = value4
+	object2 => name2
+\end{verbatim}
+
+In this syntax, we create objects with the settings defined above the object
+creation. Note that settings are inherited from the top, so in the example 
+above object2 has inherited the setting for "label1" from the first object.
+
+For template configurations, the syntax for defining a section is changed
+to:
+\begin{verbatim}
+	[section](options)
+	label = value
+\end{verbatim}
+
+The options field is used to define templates, refer to templates and hide
+templates. Any object can be used as a template.
+
+No whitespace is allowed between the closing "]" and the parenthesis "(".
+
+\subsubsection{Comments}
+
+All lines that starts with semi-colon ";" is treated as comments
+and is not parsed.
+
+The ";--" is a marker for a multi-line comment. Everything after
+that marker will be treated as a comment until the end-marker "--;"
+is found. Parsing begins directly after the end-marker.
+
+\begin{verbatim}
+	;This is a comment
+	label = value
+	;-- This is 
+	a comment --;
+	
+	;-- Comment --; exten=> 1000,1,dial(SIP/lisa)	
+\end{verbatim}
+
+\subsubsection{Including other files}
+In all of the configuration files, you may include the content of another
+file with the \#include statement. The content of the other file will be
+included at the row that the \#include statement occurred.
+	
+\begin{verbatim}
+	#include myusers.conf
+\end{verbatim}
+
+You may also include the output of a program with the \#exec directive,
+if you enable it in asterisk.conf
+	
+In asterisk.conf, add the execincludes = yes statement in the options
+section:
+\begin{verbatim}
+	[options]
+	execincludes=yes
+\end{verbatim}
+
+The exec directive is used like this:
+	
+\begin{verbatim}
+	#exec /usr/local/bin/myasteriskconfigurator.sh
+\end{verbatim}
+
+\subsubsection{Adding to an existing section}
+\begin{verbatim}
+	[section] 
+	label = value
+	
+	[section](+)
+	label2 = value2	
+\end{verbatim}	
+
+In this case, the plus sign indicates that the second section (with the
+same name) is an addition to the first section. The second section can
+be in another file (by using the \#include statement). If the section
+name referred to before the plus is missing, the configuration will fail
+to load.
+
+\subsubsection{Defining a template-only section}
+\begin{verbatim}
+	[section](!)
+	label = value
+\end{verbatim}
+
+The exclamation mark indicates to the config parser that this is a only
+a template and should not itself be used by the Asterisk module for
+configuration. The section can be inherited by other sections (see 
+section "Using templates" below) but is not used by itself.
+
+\subsubsection{Using templates (or other configuration sections)}
+\begin{verbatim}
+	[section](name[,name])
+	label = value
+\end{verbatim}
+
+The name within the parenthesis refers to other sections, either
+templates or standard sections. The referred sections are included
+before the configuration engine parses the local settings within the
+section as though their entire contents (and anything they were 
+previously based upon) were included in the new section.  For example 
+consider the following:
+
+\begin{verbatim}
+[foo]
+permit=192.168.0.2
+host=asdf
+deny=192.168.0.1
+
+[bar]
+permit=192.168.1.2
+host=jkl
+deny=192.168.1.1
+
+[baz](foo,bar)
+permit=192.168.3.1
+host=bnm
+\end{verbatim}
+
+The [baz] section will be processed as though it had been written in the 
+following way:
+
+\begin{verbatim}
+[baz]
+permit=192.168.0.2
+host=asdf
+deny=192.168.0.1
+permit=192.168.1.2
+host=jkl
+deny=192.168.1.1
+permit=192.168.3.1
+host=bnm
+\end{verbatim}
+
+\subsubsection{Additional Examples}
+
+(in top-level sip.conf)
+
+\begin{verbatim}
+[defaults](!)
+type=friend
+nat=yes
+qualify=on
+dtmfmode=rfc2833
+disallow=all
+allow=alaw
+
+#include accounts/*/sip.conf
+\end{verbatim}
+
+(in accounts/customer1/sip.conf)
+
+\begin{verbatim}
+[def-customer1](!,defaults)
+secret=this_is_not_secret
+context=from-customer1
+callerid=Customer 1 <300>
+accountcode=0001
+
+[phone1](def-customer1)
+mailbox=phone1@customer1
+
+[phone2](def-customer1)
+mailbox=phone2@customer1
+\end{verbatim}
+
+This example defines two phones - phone1 and phone2 with settings
+inherited from "def-customer1".  The "def-customer1" is a template that
+inherits from "defaults", which also is a template.
-- 
cgit v1.2.3

