File ownership and what files you can edit

Who owns what files in /etc/asterisk when FreePBX is installed?
That's what this page is here to answer.
The basic rule is that all files are owned and modified by FreePBX unless they end _custom.conf. There are a few exceptions to this rule but not many.
If the file is owned by FreePBX you should find this statement at the top of the file making it clear that it is owned by FreePBX

;--------------------------------------------------------------------------------;
; Do NOT edit this file as it is auto-generated by FreePBX. All modifications to ;
; this file must be done via the web gui. There are alternative files to make    ;
; custom modifications, details at: http://freepbx.org/configuration_files       ;
;--------------------------------------------------------------------------------;
;

So here is the list of files as of version 2.4. Those owned by FreePBX will be in bold underline. If they become owned in a later version that version will be stated to the right of the file name.
agents.conf
alarmreceiver.conf
applications.conf
asterisk.conf
backup.conf

  1. This file contains the crontab line(s) that will get executed for backup job scheduling.

cdr_mysql.conf

  1. if you want to use the userfield in the CDR reporting you will need to add this line to the file: userfield=1
    then restart Freepbx by typing amportal restart
    Default file should look like this:

     ;
 ; Note - if the database server is hosted on the same machine as the
 ; asterisk server, you can achieve a local Unix socket connection by
 ; setting hostname=localhost
 ;
 ; port and sock are both optional parameters.  If hostname is specified
 ; and is not "localhost", then cdr_mysql will attempt to connect to the
 ; port specified or use the default port.  If hostname is not specified
 ; or if hostname is "localhost", then cdr_mysql will attempt to connect
 ; to the socket file specified by sock or otherwise use the default socket
 ; file.
 ;
 [global]
 hostname=localhost
 dbname=asteriskcdrdb
 password=amp109
 user=asteriskuser
 ;port=3306
 ;sock=/tmp/mysql.sock

codecs.conf
dnsmgr.conf
dundi.conf
enum.conf
extconfig.conf
extensions.conf

  1. if you need to modify existing code code/context in extensions.conf please place your modifications in extensions_override_freepbx.conf as asterisk uses the code for the first context referance and ignores additional occurances.

extensions_additional.conf

  1. DO NOT EDIT THIS FILE, it get's regenerated each and every time you apply changes.
  2. If you need to expand on functionality of a section of code check to see if there is a include context line in the code (will end in _custom.conf) if so create that context in extensions_custom.conf and it will get called.
  3. If you need to replace the functionality in extensions_additional.conf please place it in extensions_override_freepbx.conf but read the notes about this file first.

extensions_custom.conf

  1. this is the file that you place all your custom contexts, and additional code enhancements to the FreePBX dial plan. This file will not be overwritten.

extensions_override_freepbx.conf

  1. If extensions.conf (or extensions_additional.conf) has a context or macro that you NEED to modify, you place that code here as asterisk will only execute the first occurrences of that code and ignores other occurrences. This file will not be overwritten. Be very careful as replacing an existing piece of code this way is the fastest possible way to break your system. If you are doing this you should probably think about filing for a feature request or bug fix to get it addressed properly.

features.conf
features_applicationmap_additional.conf
features_applicationmap_custom.conf
features_featuremap_additional.conf
features_featuremap_custom.conf
features_general_additional.conf
features_general_custom.conf
globals_custom.conf
iax.conf
iax_additional.conf
iax_custom.conf
iax_custom_post.conf
iax_general_additional.conf
iax_general_custom.conf
iaxprov.conf
iax_registrations.conf
iax_registrations_custom.conf
indications.conf
localprefixes.conf
logger.conf
manager_additional.conf
manager.conf
manager_custom.conf
meetme.conf
meetme_additional.conf
mgcp.conf
modem.conf
modules.conf
musiconhold_additional.conf
musiconhold.conf
musiconhold_custom.conf
oss.conf
parking_additional.inc (should no longer be used as parking was moved to features)
phone.conf
phpagi.conf
privacy.conf
queues.conf

  1. Do not edit this file in any way. Anything you can think of putting in this file can be placed into one of the _custom.comf files where it will not get removed or replaced.

queues_additional.conf

  1. Do not edit this file in any way. Anything you can think of putting in this file can be placed into one of the _custom.conf files where it will not get removed or replaced.

queues_custom.conf

  1. This is the proper location for placing any of the context specific options and lines that you might need to add before the processing of the queues_additional.conf file for your queues setup.

queues_custom_general.conf

  1. This is the proper location for placing any of the [general] context option lines that you might need to add to your queues setup.

queues_general_additional.conf

  1. Do not edit this file in any way. Anything you can think of putting in this file can be placed into one of the _custom.comf files where it will not get removed or replaced.

queues_post_custom.conf

  1. This is the proper location for placing any of the context specific options that you might need to add to the end queues setup.
    This is the file that allows you to add or remove values to those entries found in the auto-generated queue_additional.conf file. So for example you have a queue 79 that need a additional parameter added. create a context line: [79](+) then on the next line add the item(s) you need to add. To remove use (-) instead followed by the line(s) you want removed.

res_mysql.conf
rtp.conf
sip.conf

  1. Do not edit this file in any way. Anything you can think of putting in this file can be placed into one of the _custom.comf files where it will not get removed or replaced. If you are looking to do nat'ing, see sip_general_custom.conf or if it is a legacy system sip_nat.conf. If you want to add additional setup parameters for your sip device see sip_custom_post.conf, etc. If you need to adjust sip jitter or something else it will be sip_general_custom.conf (if it is for the general context) or sip_custom.conf. If you do edit this file and place something new in it, it will get overwritten at some point and next time you restart your system you will suddenly wonder why things stopped working.

sip_general_additional.conf

  1. This is where FreePBX places all of it's general context settings. If you need to override one of these or add a new one please do so in sip_general_custom.conf.

sip_general_custom.conf

  1. This is the proper location for placing any of the [general] context option lines that you might need to add to your setup. This is also the place to add those lines needed to enable the nat'ing of SIP when you go through a firewall.

    Some of the required lines for nat'ing are externip=, nat=, localnet= (you can have more then one occurrence of this line), and optionally fromdomain=. The first three are needed to properly setup a box on protected network behind a firewall that is providing nat to a public IP. If you have a legacy system these lines might have been placed in sip_nat.conf in the past, if so that is ok as long as the lines only exist in one file and not both (or a big debugging mess will occur along with hair loss as you pull it out while tracking it all down). See sip_nat.conf for more info.

    configurations with multiple subnets:
    For those setups with internal networks that have multiple subnets you will need to add a localnet= line for each subnet that the phone system should have direct access to. If you don't do this the phone system will assume that phones on those other subnets are external and thus provide the External IP of the box in the SIP headers instead of the internal IP. This then becomes a routing problem for the phone as it should not be attempting to talk external IP of the internal box (most firewalls can not handle the looping back of IP traffic).

    Example:
    Server 192.168.1.2 on a 192.168.1.0/255.255.255.0 network
    Phones inside the office are on the 192.168.2.0/255.255.255.0 subnet

    Requires these two lines in the either sip_general_custom.conf or sip_nat.conf file
    localnet=192.168.1.0/255.255.255.0
    localnet=192.168.2.0/255.255.255.0

sip_nat.conf

  1. This is the old common location for placing the lines needed to enable the nat'ing of SIP. The new preferred location is sip_general_custom.conf. If you move the lines from this file to sip_general_custom.conf please remove them from this file or you'll experience hair loss as you spend time debugging why things don't work as you expect.

sip_registrations.conf

  1. General section registrations that are auto-generated by FreePBX.

sip_registrations_custom.conf

  1. a custom file just in case there is ever a need to override a general registration that was auto-generated by FreePBX.

sip_custom.conf

  • This is the first file that is not under the general context. IT allows you to define contexts that you need before the contexts that are auto-generated by FreePBX in sip_additional.conf.

    • sip_additional.conf

    1. This is where FreePBX puts all sip extensions, sip trunks, etc. If you need to add a additional parameter to a extension, trunk, etc., see sip_custom_post.conf.

    sip_custom_post.conf

    1. This is the file that allows you to add/remove values to those entries found in the auto-generated sip_additional.conf file. So for example you have an extension 1000 that needs an additional parameter added. Create a context line: [1000](+) then on the next line add the item(s) you need to add. To remove use (-) instead followed by the line(s) you want removed.

    sip_notify.conf
    skinny.conf
    voicemail.conf

    1. This file is both editable by you and by FreePBX, so please be careful. The structure of this file is as follows:

      [general]
#include vm_general.inc
#include vm_email.inc
[default]

      Once you have configured a system with voicemail there will be values after the context [default]. These lines will be generated by FreePBX every time you add/edit/delete a extension.

      If you are looking to customize the e-mail message that get's send out with a voice mail please edit the vm_email.inc file. If you need to edit the mail sending parameters edit the vm_general.inc file. 99% of the world needs to edit two lines in the vm_general.inc file at the initial build time.

      The most common change to this file is to create a context called [zonemessages]. This context allows you to create timezones so that when you have extensions in multiple time zones they can date time stamp recorded messages properly for any given extension. If you create this context it should be placed after the second #include line and before the [default] line.

      [general]
#include vm_general.inc
#include vm_email.inc
[zonemessages]
eastern =       America/New_York|'vm-received' q 'digits/at' IMp
central =       America/Chicago|'vm-received' q 'digits/at' IMp
mountain =      America/Denver|'vm-received' q 'digits/at' IMp
pacific =       America/Tijuana|'vm-received' q 'digits/at' IMp
eastern24 =     America/New_York|'vm-received' q 'digits/at' R
central24 =     America/Chicago|'vm-received' q 'digits/at' R
mountain24 =    America/Denver|'vm-received' q 'digits/at' R
pacific24 =     America/Tijuana|'vm-received' q 'digits/at' R
deutschland =   Europe/Berlin | 'vm-received' Q 'digits/at' kM
england =       Europe/London | 'vm-received' Q 'digits/at' R
germany =       Europe/Berlin | 'vm-received' Q 'digits/at' kM
alberta =       Canada/Mountain | 'vm-received' Q 'digits/at' HM
madrid =        Europe/Paris|'vm-received' Q 'digits/at' R
paris   =       Europe/Paris|'vm-received' Q 'digits/at' R
sthlm   =       Europe/Stockholm|'vm-recieved' Q 'digits/at' R
europa  =       Europe/Berlin|'vm-received' Q 'digits/at' kM
italia  =       Europe/Rome|'vm-received' Q 'digit/at' HMP
military = Zulu | 'vm-received' q 'digits/at' H N 'hours' 'phonetic/z_p'

[default]

    vm_email.inc

    1. this file contains the e-mail subject line and message body for any voice mails that are e-mailed.

    vm_general.inc

    1. this file contains the e-mail / voice mail configuration parameters.
    2. The most common change to this file is to edit the servermail= line so that it is from a valid worldly e-mail address or any mail server that has spam and/or spoofing protection will reject the voice mail e-mails.
    3. other common lines to edit are: maxmessage= this is the max message limit, maxmsg= limits the total number of messages allowed in a mailbox, operator= if this is set to yes then when a person is leaving a message they can press 0 for the operator (or dial another extension).

    zapata.conf
    zapata-auto.conf
    zapata_additional.conf
    zapata_custom_chan_default.conf