This module will install and configure a basic asterisk instance, which is already ready to use. It provides extensive access to the configuration files of asterisk via class parameters and defines to configure singled out elements like sip/iax registrations or extensions and so on.
This module does not abstract alot of the options and names given by asterisk, since it was designed to enable fast and individually configurable instances.
To install Asterisk on a server, simply use the following:
include asteriskThis will install a plain version of Asterisk without any extra features enabled.
Some good references to consult when it comes to Asterisk configuration are:
- Online version of "Asterisk: The Definitive Guide" 3rd edition. This is definitely the best and most up to date documentation available. A must read for anyone that is configuring a PBX with Asterisk. Consult this reference if you need more information about any options that can be configured with this module. The web site mentions a 4th edition was released but it is not available online: http://asteriskdocs.org/
- A good reference for VoIP and Asterisk (some information might be outdated): http://www.voip-info.org/
- The Asterisk project wiki: https://wiki.asterisk.org/
Module origin: This module is based on the work of LeLutin, who build the
- LeLutin/asterisk module: https://forge.puppet.com/LeLutin/asterisk
The main class has a couple of parameters that configure and manage the asterisk environment.
Note that the current implementation orients on the asterisk configuration and does only
abstract where needed. Please see the code/puppet-strings documentation here
- TODO: write+generate puppet-strings in-code doc
There are default values for all configuration parameters in the asterisk::params class.
Asterisk has lots and lots of configuration variables that can be set in different files.
As you will see in some of the following configuration sections, some configuration files will be customizable through option hashes. The format of those hashes is always the same and looks like the following, where xyz would match the name of the configuration file:
$xyz_options = {
'configuration-option1' => 'value1',
'allow' => ['list-value1', 'list-value2'],
#[...]
}In order to simplify the module, we're actually not validating that the options passed in are valid ones and expect this validation to be done by the user.
We encourage users to use strings as hash keys as in the example above since some Asterisk options have dashes in their name and dashes are prohibited in puppet DSL symbols.
Some options should always be arrays: the option can be specified in the configuration file more than once to declare more values. Those options will always be set in the hashes that define default values (see in each section below) as arrays either containing a number of strings, or being empty. The module enforces that those options be arrays since it needs to iterate over them in templates. Empty arrays mean that the option should not appear in the configuration file.
Default values are taken from Debian's default configuration files.
Keys that are present in the option hash paramters to the asterisk class will
override the default options (or set new ones for options that are not present
in the default option hash). This lets you use all the default values but
change only a couple of values.
Most of the defined types that drop a configuration file in a .d directory can either take a puppet source specification (of the form 'puppet:///modules/...' or a textual content.
The puppet source specification is always used with the source parameter and
textual content with the content parameter.
When using a puppet source specification the user has complete control over the contents of the configuration file. When textual content is used, the contents will usually be added after a line that defines a configuration section (e.g. a line of the form '[section]').
source and content are always mutually exclusive.
The asterisk::iax defined type helps you configure an IAX2 channel. source
or content can be used with this type.
asterisk::iax { '5551234567':
source => 'puppet:///modules/site_asterisk/5551234567',
}The asterisk::registry::iax defined type is used to configure an IAX2
registry. All parameters (except for ensure) are mandatory. For example:
asterisk::registry::iax { 'providerX':
server => 'iax.providerX.com',
user => 'doyoufindme',
pass => 'attractive?',
}If you are using the IAX2 protocol, you'll want to set some global
configuration options. For passing in settings, you need to send a hash to the
asterisk class with the iax_options parameter.
Here is the default hash with the default values, as defined in params.pp:
$iax_options = {
'allow' => [],
'disallow' => ['lpc10'],
'bandwidth' => 'low',
'jitterbuffer' => 'no',
'forcejitterbuffer' => 'no',
'autokill' => 'yes',
'delayreject' => 'yes',
}You can configure SIP channels with the asterisk::sip defined type. source
and content can be used with this type.
asterisk::sip { '1234':
ensure => present,
secret => 'blah',
context => 'incoming',
}You can also use the template_name argument to either define a template, or
make the channel definition inherit from a template.
To define a template, set template_name to '!':
asterisk::sip { 'corporate_user':
context => 'corporate',
type => 'friend',
# ...
template_name => '!',
}If inheriting from a template, set template_name to
the name of the template from which the channel is inheriting options.
asterisk::sip { 'hakim':
secret => 'ohnoes!',
template_name => 'corporate_user',
}The defined type asterisk::registry::sip lets you configure a SIP registry.
The server and user paramters are mandatory.
asterisk::registry::sip { 'providerX':
server => 'sip.providerX.com',
user => 'doyoufindme',
}Password, authuser, port number and extension are optional parameters. If you define authuser, you must specify a password.
asterisk::registry::sip { 'friends_home':
server => 'home.friend.com',
port => '8888',
user => 'me',
password => 'myselfandI',
authuser => 'you',
extension => 'whatsupfriend',
}If you are using the SIP protocol, you'll want to set some global
configuration options. For passing in settings, you need to send a hash to the
asterisk class with the sip_options parameter.
Here is the default hash with the default values, as defined in params.pp:
$sip_options = {
'disallow' => [],
'allow' => [],
'domain' => [],
'localnet' => [],
'context' => 'default',
'allowoverlap' => 'no',
'udpbindaddr' => '0.0.0.0',
'tcpenable' => 'no',
'tcpbindaddr' => '0.0.0.0',
'transport' => 'udp',
'srvlookup' => 'yes',
'allowguest' => 'no',
'alwaysauthreject' => 'yes',
}If you want to enable SIP encryption, you can set the following settings in the
sip_options parameter to the asterisk class:
$sip_option = {
'transports' => ['tls'],
'encryption' => 'yes',
'tlsenable' => 'yes',
# Change the following two values to the full paths where you're placing your
# own certificat and CA files, respectively.
'tlscertfile' => '/etc/ssl/somecert.crt',
'tlscafile' => '/etc/ssl/someca.crt',
# Only set this to 'yes' if you can't possibly get a verifiable certificate.
'tlsdontverifyserver' => 'no',
}Note: the 'transports' option needs to be an array, so even though you only enable 'tls' as a transport, you need to enclose the string inside an array.
With the defined type asterisk::voicemail you can configure a voicemail. The
context and password parameters are mandatory:
asterisk::voicemail { '3000':
context => 'some_context',
password => '5555',
user_name => 'Bob Bobby',
email => '[email protected]',
}You can also use the optional 'pager_email' parameter to set the email that should receive a page about new voice messages.
And finally, the argument 'options' can take a hash of voicemail options like the following:
asterisk::voicemail { '3001':
context => 'blah',
password => '112233',
options => { 'attach' => 'yes', 'delete' => 'yes' },
}Voicemail can be configured through a set of options in the [general]
context. To set those options, you can pass values as a hash to the
voicemail_options parameter to the main class.
Here is the default hash with the default values, as defined in params.pp:
$voicemail_options = {
'format' => 'wav49|gsm|wav',
'serveremail' => 'asterisk',
'attach' => 'yes',
'skipms' => 3000,
'maxsilence' => 10,
'silencethreshold' => 128,
'maxlogins' => 3,
# This is not really the default value for emailbody but it makes more
# sense to be a bit more verbose by default.
'emailbody' => 'Dear ${VM_NAME}:\n\n\tjust wanted to let you know you were just ${IF($["${VM_CIDNUM}" = "${ORIG_VM_CIDNUM}"]?left:forwarded)} a ${VM_DUR} long message (number ${VM_MSGNUM})\nin mailbox ${VM_MAILBOX} from ${VM_CALLERID} <${VM_CIDNUM}>, on ${VM_DATE},\n${IF($["${VM_CIDNUM}" = "${ORIG_VM_CIDNUM}"]?so:(originally sent by ${ORIG_VM_CALLERID} on ${ORIG_VM_DATE})\nso)} you might want to check it when you get a chance. Thanks!\n\n\t\t\t\t--Asterisk\n',
'emaildateformat' => '%A, %B %d, %Y at %r',
'pagerdateformat' => '%A, %B %d, %Y at %r',
'sendvoicemail' => 'yes',
}Extensions can be set with the asterisk::extensions defined type. source or
content can be used with this type.
asterisk::extensions { 'incoming':
ensure => present,
content => template('site_asterisk/extensions/incoming.erb'),
}Some global options can be set for extensions. You can achieve that by passing
a hash to the extensions_options parameter to the asterisk class.
Here is the default hash with the default values, as defined in params.pp:
$extensions_options = {
'static' => 'yes',
'writeprotect' => 'no',
'clearglobalvars' => 'no',
}Note that by default no global variables (e.g. values set in the [globals]
context) are set. To set global variables, you can use an
asterisk::extensions resource with a context value of "globals".
To define an agent you can use the asterisk::agent defined type. The ext,
password and agent_name parameters are mandatory.
To define a static agent:
asterisk::agent { 'joe':
ext => '1001',
password => '123413425',
agent_name => 'Joe Bonham',
}You can also assign a static agent to one or more agent groups with the
groups parameter. This parameter is a list of group names:
asterisk::agent { 'cindy':
ext => '1002',
password => '754326',
agent_name => 'Cindy Rotterbauer',
groups => ['1']
}Static agents have some disadvantages compared to dynamic agents. For example, once assigned to a queue they cannot logout of that queue. For more information on how to setup dynamic agents, see:
- http://www.voip-info.org/wiki/view/Asterisk+cmd+AgentLogin
- http://www.voip-info.org/wiki/view/Asterisk+cmd+AddQueueMember
- http://www.voip-info.org/wiki/view/Asterisk+cmd+RemoveQueueMember
Some global options can be set for agents. One option in the [general]
context, multiplelogin, can be set via the agents_multiplelogin parameter
to the asterisk class with a boolean value.
Global options in the [agents] context can be set by passing a hash to the
agents_options parameter to the asterisk class. By default this parameter
doesn't define any global options.
For creating agents, it is recommended to use the asterisk::agent defined
type.
Features let you configure call parking and special numbers that trigger
special functionality. The asterisk::feature defined type helps you
configuring such features. The options parameter is mandatory.
Define features that are contained within feature group "myfeaturegroup":
$ft_options = {
'pausemonitor' => '#1,self/callee,Pausemonitor',
'unpauseMonitor' => '#3,self/callee,UnPauseMonitor',
}
asterisk::feature { 'myfeaturegroup':
options => $ft_options,
}A special section in the features configuration file, namely
[applicationmaps] lets you define global features. The
asterisk::feature::applicationmap defined type helps you configure such a
global feature. The feature and value parameters are mandatory:
asterisk::feature::applicationmap { 'pausemonitor':
feature => 'pausemonitor',
value => '#1,self/callee,Pausemonitor',
}Some global feature options can be configured, like the default parkinglot, via
the features_options parameter to the asterisk class.
Here is the default hash with the default values, as defined in params.pp:
$features_options = {
'parkext' => '700',
'parkpos' => '701-720',
'context' => 'parkedcalls',
}A special context, featuremap, lets you configure global features. By
default, no feature is configured. You can pass a hash to the
features_featuremap parameter to the asterisk class to configure features
in this context.
Another special context, applicationmap, lets you configure dynamic features.
To set entries in this context, you should use the
asterisk::feature::applicationmap defined type. Note also that for dynamic
features to work the DYNAMIC_FEATURES channel variable must be set by listing
features enabled in the channel, separated by '#'.
To configure additional feature contexts, you can use the asterisk::feature
defined type.
Asterisk can put call in queues, for example when all agents are busy and the call cannot get connected. To create a queue, you can use the asterisk::queue defined type:
asterisk::queue { 'frontline':
ensure => present,
stragegy => 'rrmemory',
members => [
'SIP/reception',
'SIP/secretary',
],
maxlen => 30,
timeout => 20,
retry => 10,
}Call queues have lots of options and can interact with agents. Because of this we will not detail all of the parameters here. Please refer to the manifests/queue.pp file for the complete list of supported parameters. Also, for an in-depth coverage of call queueing, see: http://www.asteriskdocs.org/en/3rd_Edition/asterisk-book-html-chunk/asterisk-ACD.html
For queues some global configurations and default values can be set in the
[general] context. You can set options by passing a hash to the
queues_options parameter to the asterisk class.
Here is the default hash with the default values, as defined in params.pp:
$queues_options = {
'persistentmembers' => 'yes',
'monitor-type' => 'MixMonitor',
}Configuring Asterisk modules is key to implementing your features right. Four
parameter to the asterisk class offer you the possibility to customize what
modules are loaded or not on your PBX. Default values for the parameters were
taken from the default config file in Debian.
-
modules_autoload: a boolean value (defaults totrue) that decides whether or not Asterisk will try to automatically load required modules even though they are not explicitely marked as needing to be loaded in the modules.conf file. -
modules_noload: an array of strings of explicitely unwanted modules that won't load even thoughmodules_autoloadis true. Specifying an array to this parameter overrides the default list so make sure to include all unwanted modules. The default array is the following:$modules_noload = [ 'pbx_gtkconsole.so', 'pbx_kdeconsole.so', 'app_intercom.so', 'chan_modem.so', 'chan_modem_aopen.so', 'chan_modem_bestdata.so', 'chan_modem_i4l.so', 'chan_capi.so', 'chan_alsa.so', 'cdr_sqlite.so', 'app_directory_odbc.so', 'res_config_odbc.so', 'res_config_pgsql.so' ]
-
modules_load: an array of strings of explicitely wanted modules. Specifying an array to this parameter overrides the default list so make sure to include all wanted modules. The default array is the following:$modules_load = ['res_musiconhold.so']
-
modules_global_options: a hash of options that should be set in the[global]context. These options let you customize behaviours for modules that are loaded.
Asterisk can expose an interface for managing the PBX. This interface can be offered to different users with different permissions. You can configure read and write access to certain features of the PBX for each user.
The asterisk::manager defined type helps you configure a manager access. The
secret parameter is mandatory. By default, the resource name is used as the
manager name:
asterisk::manager { 'nagios':
secret => 'topsecret1234',
read => ['all'],
write => ['system', ' call', ' log', ' verbose', ' command', ' agent', ' user'],
}Here's a paranoid version of the above configuration, with minimal network access, but the option to run system commands and trigger calls:
asterisk::manager { 'nagios':
secret => 'topsecret1234',
read => ['system', 'call'],
write => ['system', 'call'],
}Here, we permit remote management to two other systems on an internal network:
asterisk::manager { 'robocall':
secret => 'robotsdeservesomeloveafterall',
permit => ['10.10.10.200/255.255.255.0', '10.20.20.200/255.255.255.0'],
read => ['system', 'call', 'log'],
write => ['system', 'call', 'originate'],
}To override the manager name, you can use the manager_name parameter:
asterisk::manager { 'sysadmin':
secret => 'nowyouseemenowyoudont',
read => ['all'],
write => ['all'],
manager_name => 'surreptitioustyrant',
}Asterisk maintains a service on a port through which you can inspect asterisk's
state and issue commands to the PBX. You can control on which IP and port it
binds to and if it is enabled at all with three parameters to the asterisk
class.
-
manager_enable: a boolean value that decides whether or not the manager is in function. Defaults to true. -
manager_port: an integer value that specifies on which port the manager will listen. Default value is 5038. -
manager_bindaddr: a string that contains the IP address on which the manager should bind. Default value is 127.0.0.1.
By default, no user access is configured. If you want to enable users to
interact with the manager, you should declare asterisk::manager
resources.
Dahdi is a set of kernel modules combined with an asterisk module that let people interact with Digium cards to send and receive calls from the POTS. To enable dahdi, use the following:
include 'asterisk::dahdi'To include any language sounds, you can use the following (in this example, we're installing french and spanish sounds):
asterisk::language {
['fr-armelle', 'es']:
}Valid languages strings are the following (these are all based on debian package names for now -- either asterisk-prompt-X or asterisk-Y. the language strings that start with core-sounds enable you to install language sounds in a specific encoding to avoid the need for asterisk to recode it while feeding it to a device):
- de
- es-co
- fr-armelle
- fr-proformatique
- it-menardi
- it-menardi-alaw
- it-menardi-gsm
- it-menardi-wav
- se
- es
- core-sounds-en
- core-sounds-en-g722
- core-sounds-en-gsm
- core-sounds-en-wav
- core-sounds-es
- core-sounds-es-g722
- core-sounds-es-gsm
- core-sounds-es-wav
- core-sounds-fr
- core-sounds-fr-g722
- core-sounds-fr-gsm
- core-sounds-fr-wav
- core-sounds-ru
- core-sounds-ru-g722
- core-sounds-ru-gsm
- core-sounds-ru-wav
Contributions are highly welcomed, more so are those which contribute patches with tests. Or just more tests! We have rspec-puppet and rspec-system tests. When [contributing patches](Github WorkFlow), please make sure that your patches pass tests:
user@host01 ~/src/bw/puppet-composer (git)-[master] % rake spec
....................................
Finished in 2.29 seconds
36 examples, 0 failures
user@host01 ~/src/bw/puppet-composer (git)-[master] % rake spec:system
...loads of output...
2 examples, 0 failures
user@host01 ~/src/bw/puppet-composer (git)-[master] %
This module is licensed under the GPLv3+, feel free to redistribute, modify and contribute changes.
A copy of the GPLv3 license text should be included with the module. If not, check out the github repository at https://github.com/lelutin/puppet-asterisk or one of its clones.
The license text can also be downloaded from: