asterisk users - Nov 2008 - RFC: multiple packages editing asterisk config files

Hi

I'm lately bothered with the need to provide a set of Asterisk
configuration files in a package that will be good for a wide range of 
Asterisk users.

Asterisk configuration files support #include and a number of other
interesting tricks, as mentioned in
http://svn.digium.com/svn/asterisk/branches/1.4/doc/configuration.txt [0].


Let's start with manager.conf . 

Let's start with the simplest possible variant:

;;;;;;;;;;;;;;;;;;;;;;; manager.conf
[general]
enabled = yes
bindaddr = 127.0.0.1

; here come also a number of other remmed-out values for a human admin
; to edit
;webanbled = yes
;port = 5038 ; The default

#include manager.d/*.conf

; Here the human admin can add complete sections:
;[admin]
;secret = xxxxxx
;read = all
;write = all
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


Some Asterisk configuration interface (let's call our fictional one
astcfg) can then create:

/etc/asterisk/manager.d/astcfg.conf (which can also be a symlink to a
directory where astcfg can actually write[1])

;;;;;;;;;;;;;;;;;;;;;;;; /etc/asterisk/manager.d/astcfg.conf 
[general](+)
; Those settings don't necessarily make sense. They are here to
; demonstrate how configuration parsing works
bindaddr = 0.0.0.0
port = 3030

[astcfg]
secret = 209348
read =  all
write = all
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


Now for a more complicated example. sip.conf . sip.conf gives us a
little extra pain that most users have a matching 'register =>'
entry.
But we already learned how to do that: an extra [general](+) section[2]. 

As we can clearly see, it is very simple to automatically add extra
sections and to add extra directives to sections. It is impossible to
cancel sections and to cancel directiver (or "reset to default" e.g: 
reset the "port" setting so that the port in "bindaddr"
would take
effect, or vice versa) directives. I wonder if this is an actual 
limitation, and if so: if there is a simple way to overcome it.


Problems:
1. voicemail.conf . It is accessed directly from oh so many places.
Teaching all of them to respect the cool asterisk configuration files
tricks (for rewriting!) is a futile attempt. Workarounds: update
password with an external script, and only use the existing Asterisk
interfaces to check for ovicemail authentication. Practical?


What other problems would such a method have?


[0] Note that this is a link to the file from 1.4. In 1.6 the file is in
    TeX format that is slightly less readable. Any simple way to
    reference directly to the relevant chapter from the generated Asterisk 
    Book?

[1] Preventing astcfg from write access to the Asterisk config files is
    not a real protection, because:
    1. If the use of '#exec' is enabled, the astcfg can force Asterisk
       to run some script of its choosing e.g. to edit other
       configuration files.
    2. If astcfg is allowed to manipulate the dialplan in any way (e.g.:
       originate calls, it still has complete control).

    This may, however, save the need to run apache as asterisk. 

[2] If there are too many of those, we should ask ourselves how to fit 
    those register lines into the peer entries in order to simplify the
    configuration parsing.

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir

On Thu, Nov 06, 2008 at 12:57:15PM +0200, Tzafrir Cohen
wrote:
> Hi
> 
> I'm lately bothered with the need to provide a set of Asterisk
> configuration files in a package that will be good for a wide range of 
> Asterisk users.
> 
> Asterisk configuration files support #include and a number of other
> interesting tricks, as mentioned in
> http://svn.digium.com/svn/asterisk/branches/1.4/doc/configuration.txt [0].
> 
Now let's look at indications.conf .

indications.conf . This is essentially a data file. Indications should
mostly have been provided by an external library. Indications from
libtonezone and from indications.conf are the same. 

The sample^Wreference indications.conf begins, however with a warning:
; NOTE:
;    When adding countries to this file, please keep them in alphabetical
;    order according to the 2-character country codes!

I looked at main/indications.c and res/res_indications.c and fail to see
the reason for this limitation. The only configurable part in this file
follows:

[general]
country=us		; default location

Which would be easy to override anyway:

[general](+)
country = dk


There is normally never a need to remove a value. Only to add a section
or fix a wrong value. Hence I would suggest to replace the default
settings for indications.conf with:

; This would be /var/lib/asterisk if your distribution did not change it
; to something like /usr/share/asterisk ;-)
#include $AST_DATA_DIR/configs/indications.countries.conf
[general]
;country = us



-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir

On Thu, Nov 06, 2008 at 12:57:15PM +0200, Tzafrir Cohen
wrote:
> Hi
> 
> I'm lately bothered with the need to provide a set of Asterisk
> configuration files in a package that will be good for a wide range of 
> Asterisk users.
> 
> Asterisk configuration files support #include and a number of other
> interesting tricks, as mentioned in
> http://svn.digium.com/svn/asterisk/branches/1.4/doc/configuration.txt [0].
Where can we find tools to parse Asterisk configuration files?

Asterisk does not provide any library or utility to read configuration
files. The asterisk-gui uses Asterisk itself to both read and write
configuration files.

The FreeIRIS project uses a set of perl module, that are also available
in CPAN, as Asterisk::config
http://search.cpan.org/dist/Asterisk-config/
http://www.freeiris.org/

(Never tried using them)


Next file to look at is modules.conf . modules.conf is one of those
files with a "single section" (or maybe two or three, but many entries
in that section). Mostly the order in modules.conf doesn't count.
However I beleive that in some specific cases the order of entries there
does count.

In addition, of of the entries there are of the same two keys ('load'
and 'unload'). Hence it's imporssible to override an earlier
"assignment" later. This makes module.conf very unmodular (pun not
intended) by nature.

The problem with modules.conf is that a mistake in it can easily get
Asterisk to either fail to load or behave very strange.

Can someone describe to me a real-life situation where the order of 
directives in modules.conf matters?

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir

On Thu, Nov 06, 2008 at 12:57:15PM +0200, Tzafrir Cohen
wrote:
> Hi
> 
> I'm lately bothered with the need to provide a set of Asterisk
> configuration files in a package that will be good for a wide range of 
> Asterisk users.
> 
> Asterisk configuration files support #include and a number of other
> interesting tricks, as mentioned in
> http://svn.digium.com/svn/asterisk/branches/1.4/doc/configuration.txt [0].
Let's look at asterisk.conf .

Unlike most configuration files, asterisk.conf is not read on reload .
Only at startup and restart. It is read by the main asterisk thread and
variables from there are globals that may affect all parts of Asterisk.

The [directories] section is most useful for anybody who uses a custom
installation of Asterisk. Though for distributors I would recommend to
patch those values in the source. It is still very handy if you want to
have more than one copy of Asterisk on the system.

The [options] section has grown over time and includes many options.
Some of them corespond to command-line switches. It is interesting to
note that values in the configuration file override Asterisk
command-line switches of Asterisk and not vice-versa as it is the common
with Unix programs. Thus relying on setting parameters through
controlling the command-line of Asterisk is not as robust as editing
asterisk.conf . The reason for that is that on 'reastart', asterisk
re-execs itself. It retains the same command-line options. But it
re-reads asterisk.conf , and thus changes to the command-line options
would require stopping the Asterisk process and starting it again, as
opposed to using the 'restart' command in asterisk.

The [compat] section is new in the game for asterisk 1.6 . It makes it
actively danbgerous to write asterisk from scratch (as done by, well,
someone, in
http://svn.digium.com/svn/asterisk/trunk/contrib/scripts/live_ast ). In
fact, the only way blessed by the Asterisk developers to write a valid
asterisk.conf is to use the output of 'make install' .

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir