Fix escaping and some of the formattting (closes issue #10285)
[asterisk/asterisk.git] / doc / tex / configuration.tex
1 \subsubsection{Introduction}
2
3 The Asterisk configuration parser in the 1.2 version
4 and beyond series has been improved in a number of ways. In
5 addition to the realtime architecture, we now have the ability to create
6 templates in configuration files, and use these as templates when we
7 configure phones, voicemail accounts and queues.
8
9 These changes are general to the configuration parser, and works in
10 all configuration files. 
11
12 \subsubsection{General syntax}
13 Asterisk configuration files are defined as follows:
14
15 \begin{verbatim}
16         [section]
17         label = value
18         label2 = value
19 \end{verbatim}
20
21 In some files, (e.g. mgcp.conf, zapata.conf and agents.conf), the syntax
22 is a bit different. In these files the syntax is as follows:
23         
24 \begin{verbatim}
25         [section]
26         label1 = value1
27         label2 = value2
28         object => name
29
30         label3 = value3
31         label2 = value4
32         object2 => name2
33 \end{verbatim}
34
35 In this syntax, we create objects with the settings defined above the object
36 creation. Note that settings are inherited from the top, so in the example 
37 above object2 has inherited the setting for "label1" from the first object.
38
39 For template configurations, the syntax for defining a section is changed
40 to:
41 \begin{verbatim}
42         [section](options)
43         label = value
44 \end{verbatim}
45
46 The options field is used to define templates, refer to templates and hide
47 templates. Any object can be used as a template.
48
49 No whitespace is allowed between the closing "]" and the parenthesis "(".
50
51 \subsubsection{Comments}
52
53 All lines that starts with semi-colon ";" is treated as comments
54 and is not parsed.
55
56 The ";--" is a marker for a multi-line comment. Everything after
57 that marker will be treated as a comment until the end-marker "--;"
58 is found. Parsing begins directly after the end-marker.
59
60 \begin{verbatim}
61         ;This is a comment
62         label = value
63         ;-- This is 
64         a comment --;
65         
66         ;-- Comment --; exten=> 1000,1,dial(SIP/lisa)   
67 \end{verbatim}
68
69 \subsubsection{Including other files}
70 In all of the configuration files, you may include the content of another
71 file with the \#include statement. The content of the other file will be
72 included at the row that the \#include statement occurred.
73         
74 \begin{verbatim}
75         #include myusers.conf
76 \end{verbatim}
77
78 You may also include the output of a program with the \#exec directive,
79 if you enable it in asterisk.conf
80         
81 In asterisk.conf, add the execincludes = yes statement in the options
82 section:
83 \begin{verbatim}
84         [options]
85         execincludes=yes
86 \end{verbatim}
87
88 The exec directive is used like this:
89         
90 \begin{verbatim}
91         #exec /usr/local/bin/myasteriskconfigurator.sh
92 \end{verbatim}
93
94 \subsubsection{Adding to an existing section}
95 \begin{verbatim}
96         [section] 
97         label = value
98         
99         [section](+)
100         label2 = value2 
101 \end{verbatim}  
102
103 In this case, the plus sign indicates that the second section (with the
104 same name) is an addition to the first section. The second section can
105 be in another file (by using the \#include statement). If the section
106 name referred to before the plus is missing, the configuration will fail
107 to load.
108
109 \subsubsection{Defining a template-only section}
110 \begin{verbatim}
111         [section](!)
112         label = value
113 \end{verbatim}
114
115 The exclamation mark indicates to the config parser that this is a only
116 a template and should not itself be used by the Asterisk module for
117 configuration. The section can be inherited by other sections (see 
118 section "Using templates" below) but is not used by itself.
119
120 \subsubsection{Using templates (or other configuration sections)}
121 \begin{verbatim}
122         [section](name[,name])
123         label = value
124 \end{verbatim}
125
126 The name within the parenthesis refers to other sections, either
127 templates or standard sections. The referred sections are included
128 before the configuration engine parses the local settings within the
129 section as though their entire contents (and anything they were 
130 previously based upon) were included in the new section.  For example 
131 consider the following:
132
133 \begin{verbatim}
134 [foo]
135 permit=192.168.0.2
136 host=asdf
137 deny=192.168.0.1
138
139 [bar]
140 permit=192.168.1.2
141 host=jkl
142 deny=192.168.1.1
143
144 [baz](foo,bar)
145 permit=192.168.3.1
146 host=bnm
147 \end{verbatim}
148
149 The [baz] section will be processed as though it had been written in the 
150 following way:
151
152 \begin{verbatim}
153 [baz]
154 permit=192.168.0.2
155 host=asdf
156 deny=192.168.0.1
157 permit=192.168.1.2
158 host=jkl
159 deny=192.168.1.1
160 permit=192.168.3.1
161 host=bnm
162 \end{verbatim}
163
164 \subsubsection{Additional Examples}
165
166 (in top-level sip.conf)
167
168 \begin{verbatim}
169 [defaults](!)
170 type=friend
171 nat=yes
172 qualify=on
173 dtmfmode=rfc2833
174 disallow=all
175 allow=alaw
176
177 #include accounts/*/sip.conf
178 \end{verbatim}
179
180 (in accounts/customer1/sip.conf)
181
182 \begin{verbatim}
183 [def-customer1](!,defaults)
184 secret=this_is_not_secret
185 context=from-customer1
186 callerid=Customer 1 <300>
187 accountcode=0001
188
189 [phone1](def-customer1)
190 mailbox=phone1@customer1
191
192 [phone2](def-customer1)
193 mailbox=phone2@customer1
194 \end{verbatim}
195
196 This example defines two phones - phone1 and phone2 with settings
197 inherited from "def-customer1".  The "def-customer1" is a template that
198 inherits from "defaults", which also is a template.