From f6799fe097ab2a8cef7e1c540b386655882f660c Mon Sep 17 00:00:00 2001 From: Stonewall Jackson Date: Fri, 10 Feb 2023 08:55:54 -0500 Subject: add asterisk documentation --- roles/asterisk/README.md | 138 +++++++++++++++++++++++++++++++++++++++ roles/asterisk/defaults/main.yml | 2 +- roles/asterisk/tasks/main.yml | 2 +- 3 files changed, 140 insertions(+), 2 deletions(-) create mode 100644 roles/asterisk/README.md diff --git a/roles/asterisk/README.md b/roles/asterisk/README.md new file mode 100644 index 0000000..7a3db09 --- /dev/null +++ b/roles/asterisk/README.md @@ -0,0 +1,138 @@ +Asterisk +======== + +Description +----------- + +The `asterisk` role installs and configures the +[Asterisk](https://www.asterisk.org/) PBX. + +Variables +--------- + +This role **accepts** the following variables: + +Variable | Default | Description +---------------------------------------|----------------------------------------------------|------------ +`asterisk_local_nets` | `['10.0.0.0/8', '172.16.0.0/12', 192.168.0.0/16']` | Networks local to the Asterisk server (see [documentation](https://wiki.asterisk.org/wiki/display/AST/Asterisk+17+Configuration_res_pjsip#Asterisk17Configuration_res_pjsip-transport_external_media_address)) +`asterisk_external_ip` |   | External IP address of the Asterisk server (see [documentation](https://wiki.asterisk.org/wiki/display/AST/Asterisk+17+Configuration_res_pjsip#Asterisk17Configuration_res_pjsip-transport_external_media_address)) +`asterisk_timezone` | `{{ timezone }}` | Timezone used for voicemail metadata +`asterisk_locale` | `en_US.UTF-8` | Locale used for voicemail prompts +`asterisk_public_fqdn` | `{{ ansible_fqdn }}` | Public FQDN of the Asterisk server (used for SIP TLS client certificate) +`asterisk_from_domain` | `{{ email_domain }}` | Domain used in SIP `From` header +`asterisk_rtp_port_start` | 10000 | Minimum port used for RTP dynamic port range +`asterisk_rtp_port_end` | 10999 | Maximum port used for RTP dynamic port range +`asterisk_sip_port` | 5060 | Source port for SIP connections +`asterisk_sip_tls_port` | 5061 | Source port for SIP TLS connections +`asterisk_http_port` | 8088 | Listening port for the Asterisk HTTP server +`asterisk_https_port` | 8089 | Listening port for the Asterisk HTTP server (HTTPS) +`asterisk_voicemail_formats` | `['wav49', 'gsm', 'wav']` | Audio formats used for voicemail recordings +`asterisk_mail_from` | `asterisk-noreply@{{ email_domain }}` | Email address used for new voicemail notifications +`asterisk_voicemail_email_subject` | see [vars.yml](defaults/vars.yml) | Email subject line for new voicemail notifications +`asterisk_voicemail_email_body` | see [vars.yml](defaults/vars.yml) | Email body used for new voicemail notifications +`asterisk_voicemail_email_date_format` | `%A, %B %d, %Y at %r` | Email date format used for new voicemail notifications +`asterisk_voicemail_min_password` | 4 | Minimum voicemail password length +`asterisk_voicemail_max_message_count` | 100 | Maximum number of messages in each voice mailbox +`asterisk_voicemail_max_message_secs` | 300 | Maximum length of voicemail message (seconds) +`asterisk_voicemail_max_greeting_secs` | 60 | Maximum length of voicemail greeting (seconds) +`asterisk_voicemail_max_failed_logins` | 3 | Maximum number of failed voicemail logins before lockout +`asterisk_dialplan` |   | Raw dialplan to place in `extensions.conf` (see [documentation](https://wiki.asterisk.org/wiki/display/AST/Contexts%2C+Extensions%2C+and+Priorities)) +`asterisk_password_salt` |   | Salt used for generating SHA-512 password hashes +`asterisk_sip_trunks` | `[]` | Upstream SIP trunks (see format below) +`asterisk_sip_extensions` | `[]` | Local SIP extensions (see format below) +`asterisk_queues` | `[]` | Local call queues (see format below) +`asterisk_ari_users` | `[]` | User accounts for the Asterisk REST Interface (see format below) +`asterisk_voicemail_contexts` | `{}` | Dictionary of [voicemail contexts](https://wiki.asterisk.org/wiki/display/AST/Configuring+Voice+Mail+Boxes) (see format below) + + +### asterisk\_sip\_trunks + +The `asterisk_sip_trunks` variable describes your upstream SIP trunks. It should +contain a list of dictionaries of the following format: + +Key | Default | Description +-------------------|---------|------------ +`name` |   | Name of the trunk (no spaces) +`transport` | `udp` | Network transport +`host` |   | Remote SIP host (comma-separated `host:port`, or list) +`codecs` |   | Allowed codecs (comma-separated, or list) +`media_encryption` | `"no"` | Force media encryption (see [documentation](https://wiki.asterisk.org/wiki/display/AST/Asterisk+13+Configuration_res_pjsip#Asterisk13Configuration_res_pjsip-endpoint_media_encryption)) +`username` |   | SIP account username +`password` |   | SIP account password + + +### asterisk\_sip\_extensions + +The `asterisk_sip_extensions` variable describes your internal SIP extensions +(AKA your internal phone numbers). It should contain a list of dictionaries of +the following format: + +Key | Default | Description +-------------------|------------------|------------ +`name` |   | Name of the extension (usually a 3- or 4-digit number) +`codecs` |   | Allowed codecs (comma-separated, or list) +`context` |   | Dialplan context for inbound calls +`mailbox` |   | Mailbox name (comma-separated, or list) +`cid_name` |   | Caller ID name +`cid_number` | `{{ ext.name }}` | Caller ID number +`username` | `{{ ext.name }}` | Extension SIP username +`password` |   | Extension SIP password +`max_contacts` | 1 | Maximum simultaneous logins + + +### asterisk\_queues + +The `asterisk_queues` variable describes your [call queues](https://wiki.asterisk.org/wiki/display/AST/Building+Queues). + It should contain a list of dictionaries of the following format: + +Key | Default | Description +-------------------|------------------|------------ + + +### asterisk\_ari\_users + +The `asterisk_ari_users` variable describes user accounts for the [Asterisk REST Interface](https://wiki.asterisk.org/wiki/pages/viewpage.action?pageId=29395573). +It should contain a list of dictionaries of the following format: + +Key | Default | Description +------------|---------|------------ +`name` |   | Username +`password` |   | Password +`read_only` | yes | Limit account to read-only requests + + +### asterisk\_voicemail\_contexts + +The `asterisk_voicemail_contexts` variable describes your [voicemail contexts](https://wiki.asterisk.org/wiki/display/AST/Configuring+Voice+Mail+Boxes). +It should contain a mapping of context names to dictionaries of the following format: + +Key | Default | Description +-----------|---------|------------ +`address` |   | Mailbox address (usually a 3- or 4-digit number) +`password` |   | Initial mailbox password (usually a numeric PIN) +`name` |   | Human-readable mailbox name +`email` |   | Email address for new voicemail notifications (or list) + + +### Exports + +This role **exports** the following variables: + +Variable | Description +--------------------|------------ +`asterisk_data_dir` | Path to asterisk data files (voicemails, etc) + + +Usage +----- + +Example playbook: + +````yaml +- hosts: asterisk_servers + roles: + - role: asterisk + vars: + asterisk_local_nets: + - 192.168.1.0/24 +```` diff --git a/roles/asterisk/defaults/main.yml b/roles/asterisk/defaults/main.yml index e7e5b74..f47ff88 100644 --- a/roles/asterisk/defaults/main.yml +++ b/roles/asterisk/defaults/main.yml @@ -6,7 +6,7 @@ asterisk_local_nets: asterisk_timezone: '{{ timezone }}' asterisk_locale: en_US.UTF-8 -asterisk_fqdn: '{{ ansible_fqdn }}' +asterisk_public_fqdn: '{{ ansible_fqdn }}' asterisk_from_domain: '{{ email_domain }}' asterisk_rtp_port_start: 10000 diff --git a/roles/asterisk/tasks/main.yml b/roles/asterisk/tasks/main.yml index 7bb259d..a03e67a 100644 --- a/roles/asterisk/tasks/main.yml +++ b/roles/asterisk/tasks/main.yml @@ -32,7 +32,7 @@ include_role: name: certbot vars: - certificate_sans: ['{{ asterisk_fqdn }}'] + certificate_sans: ['{{ asterisk_public_fqdn }}'] certificate_path: '{{ asterisk_certificate_path }}' certificate_key_path: '{{ asterisk_certificate_key_path }}' certificate_owner: asterisk -- cgit