doc/configuration.txt

   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 occurred.
  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