Welcome to the world of telephone switch owners. Asterisk is a quite powerful
and probably one of the feature-richest open-source PBXes out there. To get you
a brief impression where to start tweaking, we've included this doc. (Thanks to
Tzafrir Cohen for a proposal of this)

File Locations
==============
See /etc/asterisk/asterisk.conf for pathnames. All the configuration is done
from the *.conf files there.

The astdatadir defaults to /usr/share/asterisk . This means that sounds
reside at /usr/share/asterisk/sounds , music-on-hold files default to
/usr/share/asterisk/moh ("directory=moh" in musiconhold.conf is relative to
the astdatadir) and likewise for images.


User, Groups, Permissions
=========================
By default the package will create user and group 'asterisk' and will run as
them. It will run with real-time priority (-p) by default. It will also add
itself to the group audio to enable the daemon to access sound cards and to 
the group dialout to access Zaptel devices. Running as root is disabled in 
/etc/init.d/asterisk for security reasons. 

To change those values you can edit /etc/default/asterisk. 

Alternatively, edit /etc/asterisk/asterisk.conf .

init.d Script Commands
======================
In addition to reload, that runs the asterisk CLI command 'reload' there
are also extensions-reload ('extensions reload') and logger-reload 
('logger-reload') to load only parts of the configuration file. 

Asterisk supports a number of non-default parameters at startup.  For debugging
it is often useful to run 'asterisk -U asterisk -vvvgc' from the console.  Add
more -v for even higher verbosity. You can attach a remote console to a running
asterisk daemon with 'asterisk -vcr'.  When testing, make sure to use the "-U
asterisk", or asterisk may write files with root ownership. In that case you
might not be able to restart the daemon without altering permissions to the
files first.

Alternatively use '/etc/init.d/asterisk debug'.

Asterisk is run with a umask of 007 by default, to allow writing 
group-owned voicemail files. To change this value, set the value if 'UMASK'
in /etc/default/asterisk .

Getting started with config and more features
=============================================
Of course the default config is far from a plug'n'play for every environment.
You need to setup a proper dialplan in extensions.conf, remove the demo entries
and maybe remove FreeWorldDialup too in case you don't participate there. For
more info on how to setup a proper dialplan, fax, enum and configuration of
asterisk, please checkout
	http://www.voip-info.org/wiki-Asterisk+quickstart
	http://www.voip-info.org/wiki-Asterisk+config+files
or the larger HowTos at:
	http://www.automated.it/guidetoasterisk.htm
or
	http://www.asteriskdocs.org/ (Asterisk Handbook)


Open Files Limit
================
Asterisk uses one file-handle (and sometimes more) per call. Hence if you 
have many simultaneous calls, you often bump into the per-process limit 
of 1024 file handles, and get the error: "Too man open files".

To enlarge that limit, set: MAXFILES in /etc/default/asterisk .
As all settings from there, apply it with:

  /etc/init.d/asterisk restart


International Sound Files
=========================
This section is for those who use an alternative set of sound files
rather than the default English ones recorded by Allison Smith. If you
use those, and never needed to set LANGUAGE/language and such - all
should work just fine.

When Asterisk is asked to play 'some/file' it will search in the the
following places on a Debian system (in whish the datadir is set to
/usr/share/asterisk)

  /usr/share/sounds/${LANG_FULL}/some/file.TYPE
  /usr/share/sounds/${LANG}/some/file.TYPE
  /usr/share/sounds/some/file.TYPE
  /usr/share/sounds/en/some/file.TYPE

TYPE is "the best available type" - the one that will take least
encoding/decoding effort. This is why you normally don't specify the
type of file to play.

FULL_LANG is a complete name of a language. For instance, "fr", "de_CH"
or "en_US_f_Allison".

LANG is just the "major language" part of FULL_LANG - only up to the
first "_", if any. So in the above examples we would get "fr", "de" and
"en".

If the language is not set, only the last two are searched.

Thus various sound file packages place their files under
/usr/share/sounds/asterisk/xx_YY_Foobar
(for sound files set Foobar of language 'xx' and country 'YY').
They also provide the alternatives 'asterisk-prompt-xx' and
'asterisk-prompt-xx-yy' for the symlinks 
/usr/share/asterisk/sounds/xx and /usr/share/asterisk/sounds/xx_YY .

If you have multiple such packages and want to change that selection, use:

  update-alternatives --config asterisk-prompt-xx

Or:

  update-alternatives --config asterisk-prompt-xx-yy

(TODO: document using an empty alternative directory for 'en' to have no
fallback sounds)


Missing Modules
===============
The following modules are included in the source tree of Asterisk but 
were not built:

* apps/app_ivrdemo.c: Disabled by default. Demo code.
* apps/app_jack.c: Depends on libresample. See TODO.Debian .
* apps/app_rpt.c: Disabled by default. Not popular. Potential quality issues.
* apps/app_skel.c: Disabled by default. Demo code.
* channels/chan_misdn.c: mISDN (1.x) only included in Experimental. See
  package misdn-user.
* channels/chan_nbs: NBS not included. Never packaged. Looks quite Asterisk 
  specific and not really useful.
* channels/chan_usbradio: Disabled by default. Not popular. Potential 
  quality issues.
* codecs/codec_resample.c: Depends on libresample. See TODO.Debian .
* pbx/pbx_gtkconsole.c: Disabled by default. Mostly pointless and adss 
  unnecessary dependencies.


DAHDI PtMP NT
=============
Short version: it doesn't work.

This package includes an experimental patch to test the support for PtMP 
NT in chan_dahdi. This is needed to e.g. connect ISDN phones. Originally
the code merely printed out "How cool would it be if someone implemented
this mode!" and bailed out. This patch merely overrides it.

At the moment it seems to provide at least basic support of ISDN phones
(that is: of dialing out from a single ISDN phone). Likewise, on a
loopback connection you can call from a TE port to the NT port but not
vice versa.

I figure that this would still be useful enough for some people, though.
But in any case, please see http://bugs.digium.com/view.php?id=15048 .


A Separate Instance
===================
Upstream maintainers are not always so keen on helping users of binary
packages. Sometimes a source build can be handy. However a simplistic
'make install' from a source distribution may not play along nicely
with your existing packages. As a workaround for that, Asterisk includes
a script called 'live_ast' to "install" Asterisk under the build root
itself.

  # For the sake of this example, I assume you work under /home/getafisk .
  # get a version of asterisk: tarball, svn, whatever
  svn co http://svn.asterisk.org/svn/asterisk/trunk asterisk-svn
  cd asterisk-svn

  # grab the script. It's already in 1.6.2 and trunk, but let's get the
  # latest:
  wget http://svn.asterisk.org/svn/asterisk/trunk/contrib/scripts/live_ast
  chmod +x live_ast
  ./live_ast conf-file
  # edit live/live.conf . Unrem 'LIVE_AST_FOR_SYSTEM=yes'
  ./live_ast configure # ./configure
  ./live_ast install   # make; make install DESTDIR=$PWD/live
  ./live_ast samples

  # As root:
  echo "DAEMON=/home/getafisk/live/asterisk" >> /etc/default/asterisk

The last line makes your private copy the actual one to use. The magic
is in /home/getafisk/live/etc/asterisk/asterisk.conf . If you need to
update something in the source, just re-run the 'install' command.
live/asterisk is a wrapper to that private copy of Asterisk.


Nat=yes by Default
==================
Short version:
As of version 1:1.6.2.9-2+squeeze4 (upstream 1.6.2.21), the default has
changged from "nat=no" to "nat=yes" in sip.conf. Chances are this is
the right setting for you, so just leave it. If you have different
configuration between peer/user settings and the global ones, you'll get
a warning. So just leave the defaults (nat=yes).

Long version:
This change is due to AST-2011-013 (CVE-2011-4597). A SIP client (UAC)
contacts Asterisk acting as a SIP server (UAS). Asterisk needs to know
where to send the response to. Originally Asterisk has followed the
recommendations in RFC 3261, Asterisk sends the response to using the
port number specified in the message. This tends to break when NAT is
involved, and hence the option "rport" was added in RFC3581: just send
it to the port number you recieved it from. This is really the sane
thing to do.

Forcing the usage of rport is probably the wise thing to do in just
about any case. Rumour has it that some Cisco phones will break if it
is used. More importantly, forcing it may break RFC3261 compliance, if
you need it. But apart from that, there's really no reason for you to
use it.

Many SIP clients just added the rport option to their requests. But
others didn't. Asterisk has added a configuration option "nat" to force
using rport ("nat=yes". This also sets a few other things). Later
versions of Asterisk have added 'nat=force_rport' that only forces rport.

The problem is that the option has to be applied even before the remote
client is fully authenticated: if the configuration differs between
different peers / users, Asterisk will have to rely on the
information in the initial request packet in order to know which user /
peer this is and send the response to the right port number (originating
or the one specified in the request).

Thus in the worst case where the global settings are not set but it is set
for each peer, a remote attacker can test if a user exists by creating
a request (e.g. INVITE) with port set to $port1 and origignating from
$port2. If the response goes to $port2, the user exists.


Enjoy your PBX!
