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