Skip to content

trefzer/puppet-asterisk

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Puppet module for Asterisk

To install Asterisk on a server, simply use the following:

include asterisk

This 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.

Requirements

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.

Extra features

Dahdi

To enable dahdi, use the following:

  include 'asterisk::dahdi'

Language sounds

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

Types

  • asterisk::extensions

    asterisk::extensions { 'incoming':
      ensure => present,
      source => "...",
    }
    
    asterisk::extensions { 'incoming':
      ensure  => present,
      content => template(...),
    }
    
    asterisk::extensions { 'incoming':
      ensure => absent,
    }
  • asterisk::sip

    asterisk::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::sip

    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',
    }
  • asterisk::iax

    This class works similarly to the asterisk::extensions class.

    asterisk::iax { '5551234567':
      source => 'puppet:///modules/site_asterisk/5551234567',
    }
  • asterisk::registry::iax

    asterisk::registry::iax { 'providerX':
      server => 'iax.providerX.com',
      user   => 'doyoufindme',
      pass   => 'attractive?',
    }
  • asterisk::voicemail

    asterisk::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::agent

    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 arguemnt.

    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::manager

    asterisk::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_name parameter:

    asterisk::manager { 'sysadmin':
      secret       => 'nowyouseemenowyoudont',
      manager_name => 'surreptitioustyrant',
    }
  • asterisk::queue

    asterisk::queue { 'frontline':
      ensure   => present,
      stragegy => 'rrmemory',
      members  => [
        'SIP/reception',
        'SIP/secretary',
      ],
      maxlen   => 30,
      timeout  => 20,
      retry    => 10,
    }
  • asterisk::feature

    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,
    }
  • asterisk::feature::applicationmap

    Define a global feature:

    asterisk::feature::applicationmap { 'pausemonitor':
      feature => 'pausemonitor',
      value   => '#1,self/callee,Pausemonitor',
    }

Notes on options

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.

IAX2 Options

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.

SIP 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 Options

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 Options

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

Agents options

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 Options

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.

Queues Options

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',
}

Modules

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 to true) 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 though modules_autoload is 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.

Manager options

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.

Upgrade notices

  • 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_type and queues_monitor_format parameters 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_options hash 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.

Patches and Testing

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] %

Still not implemented !

Types:

  • asterisk::mwi

License

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:

https://www.gnu.org/licenses/gpl-3.0.txt

About

Asterisk puppet module

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published