Add new README.configuration (bug #3527)
[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 This 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
48 Adding to an existing section
49 -----------------------------
50
51         [section] 
52         label = value
53         
54         [section](+)
55         label2 = value2 
56         
57 In this case, the plus sign indicates that the second section (with the
58 same name) is an addition to the first section. The second section can
59 be in another file (by using the #include statement). If the section
60 name referred to before the plus is missing, the configuration will fail
61 to load.
62
63 Defining a template-only section
64 --------------------------------
65         [section](!)
66         label = value
67
68 The exclamation mark indicates to the config parser that this is a only
69 a template and should not itself be used by the Asterisk module for
70 configuration. The section can be inherited by other sections (see 
71 section "Using templates" below) but is not used by itself.
72
73 Using templates (or other configuration sections)
74 -------------------------------------------------
75         [section](name[,name])
76         label = value
77
78 The name within the parenthesis refers to other sections, either
79 templates or standard sections. The referred sections are included
80 before the configuration engine parses the local settings within the
81 section as though their entire contents (and anything they were 
82 previously based upon) were included in the new section.  For example 
83 consider the following:
84
85 [foo]
86 permit=192.168.0.2
87 host=asdf
88 deny=192.168.0.1
89
90 [bar]
91 permit=192.168.1.2
92 host=jkl
93 deny=192.168.1.1
94
95 [baz](foo,bar)
96 permit=192.168.3.1
97 host=bnm
98
99 The [baz] section will be processed as though it had been written in the 
100 following way:
101
102 [baz]
103 permit=192.168.0.2
104 host=asdf
105 deny=192.168.0.1
106 permit=192.168.1.2
107 host=jkl
108 deny=192.168.1.1
109 permit=192.168.3.1
110 host=bnm
111
112 Additional Examples:
113 --------------------
114
115 (in top-level sip.conf)
116
117 [defaults](!)
118 type=friend
119 nat=yes
120 qualify=on
121 dtmfmode=rfc2833
122 disallow=all
123 allow=alaw
124
125 #include accounts/*/sip.conf
126
127 (in accounts/customer1/sip.conf)
128
129 [def-customer1](!,defaults)
130 secret=this_is_not_secret
131 context=from-customer1
132 callerid=Customer 1 <300>
133 accountcode=0001
134
135 [phone1](def-customer1)
136 mailbox=phone1@customer1
137
138 [phone2](def-customer1)
139 mailbox=phone2@customer1
140
141 This example defines two phones - phone1 and phone2 with settings
142 inherited from "def-customer1".  The "def-customer1" is a template that
143 inherits from "defaults", which also is a template.
144
145