[Asterisk-cvs] asterisk/doc README.configuration,NONE,1.1

[markster at lists.digium.com]

Update of /usr/cvsroot/asterisk/doc
In directory mongoose.digium.com:/tmp/cvs-serv14152/doc

Added Files:
	README.configuration 
Log Message:
Add new README.configuration (bug #3527)


--- NEW FILE: README.configuration ---
Asterisk Configuration Parser (version 1.1 and later)
-----------------------------------------------------

The Asterisk configuration parser in the 1.1 development version (1.2
stable) 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.

This changes are general to the configuration parser, and works in
all configuration files. 

General syntax
--------------
Asterisk configuration files are defined as follows:

	[section]
	label = value
	label2 = value

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:
	
	[section]
	label1 = value1
	label2 = value2
	object => name

	label3 = value3
	label2 = value4
	object2 => name2

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 
	[section](options)
	label = value

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 "(".


Adding to an existing section
-----------------------------

	[section] 
	label = value
	
	[section](+)
	label2 = value2	
	
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.

Defining a template-only section
--------------------------------
	[section](!)
	label = value

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.

Using templates (or other configuration sections)
-------------------------------------------------
	[section](name[,name])
	label = value

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:

[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

The [baz] section will be processed as though it had been written in the 
following way:

[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

Additional Examples:
--------------------

(in top-level sip.conf)

[defaults](!)
type=friend
nat=yes
qualify=on
dtmfmode=rfc2833
disallow=all
allow=alaw

#include accounts/*/sip.conf

(in accounts/customer1/sip.conf)

[def-customer1](!,defaults)
secret=this_is_not_secret
context=from-customer1
callerid=Customer 1 <300>
accountcode=0001

[phone1](def-customer1)
mailbox=phone1 at customer1

[phone2](def-customer1)
mailbox=phone2 at customer1

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.