To install Asterisk on a server, simply use the following:
include asteriskThis will install a plain version of Asterisk without any extra features enabled.
Users that are upgrading (e.g. switching or merging to current master) should consult the section named "Upgrade notices" near the end.
In order to use this module, you need the stdlib module from:
https://github.com/puppetlabs/puppetlabs-stdlib
You should also make sure that augeas is available since it is used to enable
the service in /etc/default/asterisk.
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:
- de
- es-co
- fr-armelle
- fr-proformatique
- it-menardi
- it-menardi-alaw
- it-menardi-gsm
- it-menardi-wav
- se
- es
-
asterisk::extensionsasterisk::extensions { 'incoming': ensure => present, source => "...", } asterisk::extensions { 'incoming': ensure => present, content => template(...), } asterisk::extensions { 'incoming': ensure => absent, }
-
asterisk::sipasterisk::sip { '1234': ensure => present, secret => 'blah', context => 'incoming', } asterisk::sip { '1234': ensure => absent, }
You can also use the 'template_name' argument to either define a template, by giving it a value of '!', or inherit from a template:
asterisk::sip { 'corporate_user': context => 'corporate', type => 'friend', # ... template_name => '!', } asterisk::sip { 'hakim': secret => 'ohnoes!', template_name => 'corporate_user', }
-
asterisk::registry::sipasterisk::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', }
-
asterisk::iaxThis class works similarly to the asterisk::extensions class.
asterisk::iax { '5551234567': source => 'puppet:///modules/site_asterisk/5551234567', }
-
asterisk::registry::iaxasterisk::registry::iax { 'providerX': server => 'iax.providerX.com', user => 'doyoufindme', pass => 'attractive?', }
-
asterisk::voicemailasterisk::voicemail { '3000': context => 'some_context', password => '5555', user_name => 'Bob Bobby', email => '[email protected]', }
You can also use the optional 'pager_email' 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' }, }
-
asterisk::agentTo 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
groupsarguemnt.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:
-
asterisk::managerasterisk::manager { 'nagios': secret => 'topsecret1234', read => ['all'], write => ['system', ' call', ' log', ' verbose', ' command', ' agent', ' user'], }
paranoid 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'], }
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'], }
By default, the resource name is used as the manager name. To override the manager name, you can use the
manager_nameparameter:asterisk::manager { 'sysadmin': secret => 'nowyouseemenowyoudont', manager_name => 'surreptitioustyrant', }
-
asterisk::queueasterisk::queue { 'frontline': ensure => present, stragegy => 'rrmemory', members => [ 'SIP/reception', 'SIP/secretary', ], maxlen => 30, timeout => 20, retry => 10, }
-
asterisk::featureDefine 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, }
-
asterisk::feature::applicationmapDefine a global feature:
asterisk::feature::applicationmap { 'pausemonitor': feature => 'pausemonitor', value => '#1,self/callee,Pausemonitor', }
Asterisk has lots and lots of configuration variables that can be set in different files. 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.
As you will see in some of the following sections, some configuration files will be customizable through option hashes. The format of those hashes is always the same and looks like the following:
$xyz_options = {
'configuration-option1' => 'value1',
'allow' => ['list-value1', 'list-value2'],
#[...]
}We encourage users to use strings as hash keys since some Asterisk options have dashes in their name and dashes are prohibited in hash heys as 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 generally 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. We enforce that those options be arrays since we need 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.
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 = {
'disallow' => ['lpc10'],
'bandwidth' => 'low',
'jitterbuffer' => 'no',
'forcejitterbuffer' => 'no',
'autokill' => 'yes',
}See the complete list of all available options.
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',
}Here a complete list of all available options, should be added.
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',
}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".
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.
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.
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.
For more information on configuring modules, you can consult this wiki page.
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.
-
The module used to manage files under /etc/asterisk/file.conf.d for all values of "file" that were managed. Things have been moved to /etc/asterisk/file.d, so before upgrading you should remove all .conf.d directories (all files under the old dirs will be automatically recreated in the new directories).
-
The defines that were previously named asterisk::context::xyz (or transitorily asterisk::snippet::xyz) are now named asterisk::xyz. Users will need to adjust their manifests to upgrade.
-
The
queues_monitor_typeandqueues_monitor_formatparameters to the default class were removed in favor of using quoted strings in the options array. Users who used those two options need to place their values in the$queues_optionshash with 'monitor-type' and 'monitor-format' strings as keys, respectively. To ensure that 'monitor-type' is not present in the config file, simply leave it out (as opposed to the previous behaviour of the option that required an empty string for this). -
Some default values were removed and some others were modified to be closer to default Debian config files. You should verify that new values or variables that disappear won't have an impact on your setup.
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] %
Types:
asterisk::mwi
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: