Skip to main content

Installation and Setup on OS X

Archived Page​

Archived Obsolete - No Longer Maintained

As of October 7, 2015, this page is no longer maintained by the original author and is marked as archived. It is replaced by:

macOS

macOS Installation

macOS Customization

Introduction​

What Can You Do With FreeSWITCH™?
FreeSWITCH™ is a software program that controls and manages VOIP phones and connections to Internet telephony service providers (ITSP) and other phone systems. To illustrate some features, here is an incoming call to our system: Normal ringing is replaced by: “Hi Jenna, hold on while our phones ring", phones ring and Jenna hears music, after 25 seconds: “hold on Jenna while we ring our iPhones", internal phones keep ringing and multiple iPhones ring, if no answer: “sorry we missed you Jenna, please leave a message", Jenna’s voicemail is taken and emailed to the iPhones!

What Is This Page?
This is a complete guide for installing FreeSWITCH™ and its minimum prerequisites on OS X, including instructions for establishing 24x7 operation on a Mac.

Who Is This For?
This document is for people not familiar with Unix commands and directories. The detailed explanations insinuate a long procedure, don't let that deter you, it takes about two hours to have the sample FreeSWITCH™ configuration running on OS X, not including backups.

What You Should Already Know
You must know your way around the OS X Finder, Dock and Textedit. You should also be familiar with the standard OS X folders (directories) such as Applications, Utilities, Downloads, Users, etc.

New To You
A new folder (directory) called /usr/local, it's part of the UNIX standard directories. We'll use a few Unix commands such as: cd, mkdir, ls, cp, mv,chmod, chown, and sudo. You don't need to learn about them unless you change the steps or directories used in this document.

How This Procedure Was Developed
FreeSWITCH™ is tested on a Mac Mini, iMac or MacBook Pro. The 24x7 FreeSWITCH™ runs on a headless Mac Mini.

Buy The Book!
The best way to learn how to configure and customize FreeSWITCH™ is to buy the books, you will save yourself a lot of time!

Support the Developers
PLEASE CONTRIBUTE donations, dinners, gifts, bounties, etc. to the FreeSWITCH™ developers who write and maintain this FANTASTIC software!

Some History
I replaced a VOIP PBX in 2010 with a Mac Mini running FreeSWITCH™ for home and business. There was little OS X information so I documented what I learned through searching, trial and error, the FreeSWITCH™ mailing list, etc. and created this page Nov 22, 2010. It was extensively updated and split into multiple pages Mar 21, 2013. This is the latest major change in ongoing updates.
Mario G April 28, 2014

Installation​

Using an Upgraded OS X or Xcode

All testing for these instructions was performed on a clean/non-upgraded OS X and Xcode system, without issues. Most upgraded OS X or Xcode systems will work depending on the level of the oldest software. Some upgraded systems had problems due to old files left in different directories.

The OS X FreeSWITCH™ Installer

If the OS X system is 10.8 or later, consider using the OS X FreeSWITCH™ Installer. It automates most of the steps in the release instructions below and saves a lot of time! Check it out at macOS macFI Installation.

Select OS X Release​

To manually install FreeSWITCH™ on OS X, click a link below to view instructions. The pages link back here to continue.

FreeSWITCH™ OS X Release Status

ReleaseTestedInstallation Wiki Page
10.11.0 El CapitanOctober 3, 2015Installation on OS X 10.11 El Capitan
10.10.5 YosemiteOctober 3, 2015Installation on OS X 10.10 Yosemite
10.9.5 MavericksOctober 3, 2015Installation on OS X 10.9 Mavericks
Mac OS X ArchiveMacOS Archive

xxx

Installation is Complete​

This section is used to allow the previous pages to return to this location. Do not remove this section.

Test FreeSWITCH™!​

Startup From the Command Line​

The time has come to start FreeSWITCH™ in a Terminal window:

  cd /usr/local/freeswitch/bin
  ./freeswitch

There are many startup messages ending with some text boxes containing the names of the developers.

Test the FreeSWITCH™ Command Prompt​

After all startup messages are displayed a command prompt appears, messages may continue as the prompt remains. Try a few FreeSWITCH™ commands:

  version
  status
  sofia status

If the commands return responses FreeSWITCH™ is working and you can continue with the next step.

Test A Phone​

Test using a physical SIP phone or soft phone such as Bria, or search the OS X App Store for "SIP" for a free download of Telephone. Setup the phone using the IP address of the Mac FreeSWITCH™ is running on. The port is 5060, user IDs 1000-1019 with a password of 1234 are pre-configured. Additional information is at Test Calls. Test as many functions as you can to experience the potential of FreeSWITCH™.

Shutdown FreeSWITCH™​

Issue the following command in the FreeSWITCH™ Terminal window:

  shutdown

What Next?​

Read Configuring FreeSWITCH to learn about the various configuration files and "poke around" the sample configuration in the /usr/local/freeswitch/conf folder. To setup the gateway to your ITSP and dialplans so you can make and receive calls these files require changing:

  • Gateway to your ITSP in conf/sip_profiles
  • User extensions in conf/directory/default
  • Outgoing dialplans in /conf/dialplan/default
  • Incoming dialplans in /conf/dialplan/public

These are default directories, files can be placed in other locations. In addition there are other files for IVR, sounds, etc. you should become familiar with. And don't forget the FreeSWITCH™ documentation.

To find parameters in configuration files easily you should learn how to use Grep, a Unix find tool. Grep will search for text in the directory and display lines with matching text. For instance, if you want to find where the word "mail" is used type the following command:

  grep mail conf/*
  grep -r mail conf/*    # The -r (recursive) option includes all subdirectories in the search.

Setting Up 24x7 Operation​

OS X Maximum Number of Open Files Limit​

limit.maxfiles.plist

This issue has been resolved in FreeSWITCH and is no longer needed as of Jan 5 2015. This note will be removed at a later date.

Starting with OS X 10.10 Yosemite, Apple has significantly reduced the default value for the maximum number of open files a program process can have. Due to an anomaly in FreeSWITCH™ handling of music audio files this limit is easily reached in a few hours. These instructions show you how to avoid the problem. Hopefully, this is a temporary problem, if a solution is found this section will be updated. But for now, this is needed if you plan to run FreeSWITCH on OS X 10.10.

If FreeSWITCH™ is to run from a command line for more than a few hours, the maxfiles limit must be increased via the Terminal command line as follows :

ulimit -a            <- This displays all the limits, check the first value in the "open files" line
ulimit -n ######     <- Replace ###### with a value larger than the default, for instance 100000

If you plan to use the autostart script below, then the OS X default for the launchd daemon must be increased. Follow these steps:

  1. Open a new document in TextEdit, then expand and copy the following text to it, you may change the maxfiles values if desired.
    limit.maxfiles.plist
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
    <dict>
    <key>Label</key>
    <string>limit.maxfiles</string>
    <key>ProgramArguments</key>
    <array>
    <string>launchctl</string>
    <string>limit</string>
    <string>maxfiles</string>
    <string>1500000</string>
    <string>1500000</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>ServiceIPC</key>
    <false/>
    </dict>
    </plist>
  2. Save the file as limit.maxfiles.plist on the Desktop, make sure it is a text file! The next steps are performed in a Terminal command line.
  3. sudo chmod 644 ~/Desktop/limit.maxfiles.plist
  4. sudo chown -R root:wheel ~/Desktop/limit.maxfiles.plist
  5. sudo mv ~/Desktop/limit.maxfiles.plist /Library/LaunchAgents <- If you want to keep the original on the Desktop, change mv to cp.

Create Dummy Command File​

Some steps in this section require a command script file. This is a file that you can double click to run in the Terminal application. More importantly, these files are also used for automatic startup functions.

Command files are simple text files containing Terminal commands with the file's permission changed to become executable. Rather than repeat this process for each file, create a dummy command file that will serve as a skeleton and retain its permissions when copied. The files are saved in /usr/local/freeswitch-scripts but you can place them anywhere. Once a command text file is created it can be opened and saved in Textedit or Xcode, whatever is your preference, without any extra steps.

  • Create the /usr/local/freeswitch-scripts directory: 
   mkdir /usr/local/freeswitch-scripts
  1. Start Textedit
  2. Paste the two lines below into the empty document: 
#!/bin/bash  
exit 0

Make sure they are saved as text:

  1. Pull down the Format menu
  2. Select Make Plain Text, if the default for saving text is already Plain Text, this step is not needed.
  3. Save the file in /usr/local/freeswitch-scripts as dummy.command. While the file window is open press command+shift+.(period) to view hidden files.
  4. You may see examples with #!/bin/sh as the first line, either will work in any of these scripts.

Start the Terminal application, switch to the new directory and enter the chmod command to make the file executable:

  cd /usr/local/freeswitch-scripts
  chmod +x dummy.command

Create the FreeSWITCH™ Command Script​

The command to start FreeSWITCH™ is /usr/local/freeswitch/bin/freeswitch -parm1 -parm2…. You can start the freeswitch program using this simple command. However, it's much better to use a bash script which starts FreeSWITCH™.

Consider these requirements for a 24x7 phone system:

  • Should start automatically when the computer powers up
  • Should restart itself due to a failure such as program crash
  • Should restart in case it was accidentally manually shutdown
  • Should not restart if available resources such as TCP ports are not available
  • Write messages to the console so problems can be determined easily
  • Allow easy updating of startup parameters without requiring a reboot

These are all accomplished using the instructions and script below. You can change or add parameters such as -nonat or -nc. However, the -nc option is required to run freeswitch as a background process from the bash script.

From the new directory, enter the command below to create the freeswitch.command file, it can be placed anywhere but you must change the Launchd plist to match the location.

  cp dummy.command freeswitch.command

Open the freeswitch.command file in the editor and replace the two lines with the following bash script (tested on OS X 10.6, 10.7, 10.8, 10.9):

Click here to view the entire script...

#!/bin/sh #set -xv # For debugging set -f # Turn off globbing due to the "*" returned by the netstat command

Internal functions

function writelog () { syslog -s -k Facility com.apple.console \ -k Level notice \ -k Message "$1"

printf "%b\n" "freeswitch-startup - $1" # <- echo does not put NL back in and displays bunched up on terminal }

Test to see if freeswitch is still running, should never occur

function check_fs () { local a=( $(ps axo pid,command | grep "/bin/[f]reeswitch") ) # place pid in array - /bin excludes finding freeswitch-cli if [[ $a = "" ]] ; then return 0 fi pid=${a[0]} # Pass first element (pid number) return 1 }

function check_tcp () {

Test if OS X just started and TCPIP is ready, otherwise FS wont connect to gateways

while : ; do local a=$(/usr/sbin/netstat -a -p tcp) writelog "${a}" if [[ "$a" = ESTABLISHED ]] ; then writelog "freeswitch-startup - TCPIP is available" writelog "${a}" break fi writelog "freeswitch-startup - Waiting for TCPIP, retry in 3 seconds" sleep 3 done }

function check_sip { while : ; do local a=$(/usr/sbin/netstat -a -p $1) writelog "${a}" if [[ "$a" != sip ]] ; then writelog "freeswitch-startup - SIP is clear on $1" break fi writelog "freeswitch-startup Port 5060 still in use by $1 - retry in 3 seconds" sleep 3 done }

Main flow starts here

Test to see if freeswitch is still running, should never occur under normal operation at this point

while : ; do check_fs rc=$? if [[ $rc = 0 ]]; then break fi writelog "freeswitch-startup - freeswitch process $pid is still running, retry in 3 seconds" sleep 3 done

check_tcp # Make sure TCPIP is up

If FS is shutdown and started quickly, must wait for SIP port to clear or FS profile "internal" fails to start.

Test TCP and UDP separately since plain netstat may contain "sip" characters elsewhere.

check_sip tcp check_sip udp

OS_Version=$(sw_vers -productVersion | sed "s:.[[:digit:]]*.$::g") if [[ ${OS_Version} == 10.7 ]] | [[ ${OS_Version} == 10.8 ]] | [[ ${OS_Version} == 10.9 ]]; then # Bug in 10.789 causes netstat to show ports clear but they are not - Mario G 2012-03-26 writelog "freeswitch-startup - FreeSwitch waiting for 60 seconds due to 10.8 bug" sleep 60 fi

Start freeswitch - do NOT use nohup and & since FS starts a new pid and the wrong one would be returned in check_fs

writelog "freeswitch-startup - FreeSwitch is being started, script will wait until FreeSwitch is stopped" /usr/local/freeswitch/bin/freeswitch -nc -nonat

Now wait for freeswitch to end, otherwise Launchd will restart this script when it ends

check_fs writelog "freeswitch-startup - Waiting for FreeSwitch process $pid to terminate" while [ $(ps -p $pid -o 'pid=') ]; do sleep 15; done writelog "freeswitch-startup - script has ended" exit 0

Save the file, remember it's already executable.
Make sure FreeSWITCH™ is not running and double click the file to test and start FreeSWITCH™. You can use this to manually start FreeSWITCH™ anytime.

Automatic Startup and Shutdown​

Although there are a few ways to automatically start programs on OS X, only two are covered here. Both are the current recommended methods for automatically starting programs on OS X. If you depend on FreeSWITCH™ running 24x7 be sure to start the script using Launchd method below since it has many advantages.

Autostart Using Login Items​

This technique starts FreeSWITCH™ as a "foreground" Terminal application. This is useful for testing FreeSWITCH™ when it's automatically started after a reboot and you require all console messages easily viewable. Starting FreeSWITCH™ in a Terminal window has one serious disadvantage: Terminal stores the console messages in memory. Once memory becomes full the Mac will slow down and may not respond. Consequently you would have to restart FreeSWITCH™ regularly depending on the number of messages. This is not useful for running a normal production system.

Setup OS X Account to Autostart FreeSWITCH™​

This runs the command file every time the user logs in manually or automatically. If FreeSWITCH™ is shutdown using this startup process, it will _not_automatically restart.

  1. Start System Preferences
  2. Click Accounts
  3. Click Logon Items
  4. Check "+"
  5. Navigate to the freeswitch.command file and click Add.

Autostart Using Launchd​

The OS X Launchd daemon can be used to start FreeSWITCH™ when OS X starts or preferably when the user logs on. We'll cover how to automatically start FreeSWITCH™ when the user logs on. If FreeSWITCH™ is shutdown using this startup process, it will automatically restart.

Create the FreeSWITCH™ plist​

First, we create a "property list" file, also known as a "plist" that will:

  • Start FreeSWITCH™ when the user logs on or is auto logged on
  • Restart FreeSWITCH™ as soon as it stops for any reason including manual or auto shutdown and crashes
  1. Start Textedit
  2. Paste the lines below into the empty document
  3. Pull down the Format menu
  4. Select Make Plain Text
  5. Save the file in /users/yourid/Library/LaunchAgents as org.freeswitch.freeswitch.plist, yourid is the user home directory
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
      <key>KeepAlive</key>
           <true/>
      <key>Label</key>
           <string>org.freeswitch.freeswitch</string>
      <key>ProgramArguments</key>
      <array>
           <string>/usr/local/freeswitch-scripts/freeswitch-startup.command</string>
      </array>
      <key>RunAtLoad</key>
            <true/>
      <key>ServiceIPC</key>
           <true/>
 </dict>
 </plist>

Although FreeSWITCH™ is started via the script, the freeswitch program could be executed directly from this plist, that is not recommended.

Test the FreeSWITCH™ plist​

Make sure FreeSWITCH™ is down. Then in Terminal execute the follow command:

  launchctl load ~/Library/LaunchAgents/org.freeswitch.freeswitch.plist

Now check if FreeSWITCH™ is running by either:

  1. Test your phones
  2. Launch Activity Monitor
  3. In Terminal, run /usr/local/freeswitch/bin/freeswitch-cli

If FreeSWITCH™ is running, you can shut it down by issuing:

  launchctl unload ~/Library/LaunchAgents/org.freeswitch.freeswitch.plist

Or from Terminal either of these commands would work from the freeswitch/bin directory:

  freeswitch -stop
  freeswitch-cli -x shutdown

 #### Shutdown Using Launchd

The OS X Launchd daemon can be also be used to shutdown FreeSWITCH™. This is not needed during OS X shutdown because OS X sends shutdown signals to all of the running programs. However, you may find it desirable to automatically recycle FreeSWITCH™ for problem determination. Or you may just feel more comfortable knowing FreeSWITCH™ is recycled at a set day and time.

Create Shutdown Script​

Start Terminal and enter this command to create the freeswitch-shutdown.command file in directory freeswitch-scripts:

  cp dummy.command freeswitch-shutdown.command

Open the file in the editor and add the following line as the second line of the file (between the existing two lines):

/usr/local/freeswitch/bin/freeswitch-cli -x "shutdown"

Save the file, remember it's already executable.
Make sure FreeSWITCH™ is up and double click the file to test it. If FreeSWITCH™ shuts down then proceed with the next steps.

Create Shutdown plist​

Next, create the plist file for Launchd:

  1. Start Textedit
  2. Paste the lines below into the empty document
  3. Pull down the Format menu
  4. Select Make Plain Text
  5. Change yourid to the id of the home directory and change the time shutdown will occur if needed (the example below is set for 2am each Sunday morning)
  6. Save the file in /users/yourid/Library/LaunchAgents as org.freeswitch.shutdown.plist, yourid is the user home directory
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
        <key>Label</key>
             <string>org.freeswitch.shutdown</string>
        <key>ProgramArguments</key>
        <array>
             <string>/usr/local/freeswitch-scripts/freeswitch-shutdown.command</string>
        </array>
        <key>RunAtLoad</key>
             <false/>
        <key>StartCalendarInterval</key>
        <dict>
             <key>Weekday</key>
                  <integer>7</integer>
             <key>Hour</key>
                  <integer>2</integer>
             <key>Minute</key>
                  <integer>0</integer>
        </dict>
   </dict>
   </plist>

You can either restart the Mac or issue the following command to activate the plist:

  launchctl load ~/Library/LaunchAgents/org.freeswitch.freeswitch-shutdown.plist

 #### Diagnosing plist Problems

If you receive the following message: launchctl: no plist was returned for:…..plist it usually means there was some type of error in the format of the plist. Open the OS X Console application in the Applications/Utilities folder to view messages.

Create A freeswitch-CLI Command Script​

Once FreeSWITCH™ is running in background mode you will need to use freeswitch-cli to communicate with it. Rather than starting Terminal and having to type the path to freeswitch-cli you can simply double click an icon to launch directly to freeswitch-cli.

Create the freeswitch-cli.command file in directory freeswitch-scripts:

  cp dummy.command freeswitch-cli.command

Next, add a line containing the command needed to start freeswitch-cli. Edit the new file and add the following line as the second line of the file (between the existing two lines):

/usr/local/freeswitch/bin/freeswitch-cli

Since it's already executable just double click the icon while FreeSWITCH™ is running and freeswitch-cli will communicate with it. You may want to place an alias of the script on the Desktop for easy access.

Log Segmentation and Clearing​

FreeSWITCH™ has a lot of logging options and the log files can become quite large. This section illustrates how to make OS X automatically trigger events to control logging.

Automatic Log Segmentation​

By default, the freeswitch.log file is appended to each time FreeSWITCH™ starts, and segments when its size reaches about 10 megabytes. This can be changed. However, FreeSWITCH™ does not have a mechanism to segment by time or day. By creating two files in OS X we can accomplish day and time controlled segmentation.

Create Log Segment Script​

Start Terminal and enter this command to create the freeswitch-logseg.command file in directory freeswitch-scripts:

  cp dummy.command freeswitch-logseg.command

Open the file in the editor and add the following line as the second line of the file (between the existing two lines).

kill -HUP `cat /usr/local/freeswitch/run/freeswitch.pid`

Save the file, remember it's already executable.

Make sure FreeSWITCH™ is up and double click the file to test it. View the /usr/local/freeswitch/log directory, if the log was segmented proceed with the next steps.

Create Log Segment plist​

Next, the plist file Launchd requires is created:

  1. Start Textedit
  2. Paste the lines below into the empty document
  3. Pull down the Format menu
  4. Select Make Plain Text
  5. Change yourid to the id of the home directory and change the time segmentation will occur if needed (23:59 is right before midnight)
  6. Save the file in /users/yourid/Library/LaunchAgents as org.freeswitch.logseg.plist, yourid is the user home directory
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
        <key>Label</key>
              <string>org.freeswitch.logseg</string>
        <key>ProgramArguments</key>
        <array>
             <string>/usr/local/freeswitch-scripts/freeswitch-logseg.command</string>
        </array>
        <key>RunAtLoad</key>
             <false/>
        <key>StartCalendarInterval</key>
        <dict>
             <key>Hour</key>
                  <integer>23</integer>
             <key>Minute</key>
                  <integer>59</integer>
        </dict>
   </dict>
   </plist>

You can either restart the Mac or issue the following command to activate the plist:

  launchctl load ~/Library/LaunchAgents/org.freeswitch.freeswitch-logseg.plist
Automatic Log Clearing​

Most likely you will want to erase old FreeSWITCH™ logs to free up disk space. This procedure will run periodically to delete files older than the number of days specified in a script.

Create Log Clear Script​

Start Terminal and enter this command to create the freeswitch-logclr.command file in directory freeswitch-scripts:

  cp dummy.command freeswitch-logclr.command

Open the file in the editor and add the following line as the second line of the file (between the existing two lines). Notice that mtime is set so files older than 14 days are deleted. You can change this to any valid mtime value.

/usr/bin/find /usr/local/freeswitch/log -name "freeswitch.log.*" -mtime +14 -delete

Save the file, remember it's already executable.

Make sure FreeSWITCH™ is up and double click the file to test it. View the /usr/local/freeswitch/log directory, if old logs were cleared proceed with the next steps.

Create Log Clear plist​

Next, the plist file Launchd requires is created:

  1. Start Textedit
  2. Paste the lines below into the empty document
  3. Pull down the Format menu
  4. Select Make Plain Text
  5. Change yourid to the id of the home directory and change the time clearing will occur if needed (day 0 00:00 is Sunday midnight)
  6. Save the file in /users/yourid/Library/LaunchAgents as org.freeswitch.logclr.plist, yourid is the user home directory
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
   "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
        <key>Label</key>
              <string>org.freeswitch.logclr</string>
        <key>ProgramArguments</key>
        <array>
             <string>/usr/local/freeswitch-scripts/freeswitch-logclr.command</string>
        </array>
        <key>RunAtLoad</key>
             <false/>
        <key>StartCalendarInterval</key>
        <dict>
             <key>Day</key>
                  <integer>0</integer>
             <key>Hour</key>
                  <integer>0</integer>
             <key>Minute</key>
                  <integer>0</integer>
    </dict>
   </dict>
   </plist>

You can either restart the Mac or issue the following command to activate the plist:

  launchctl load ~/Library/LaunchAgents/org.freeswitch.freeswitch-logclr.plist
Automatic Log Rename at Login​

FreeSWITCH™ does not segment the log file when it is shutdown and restarted, it simply appends to the previous log file. Use this procedure to rename the last log file before FreeSWITCH™ starts at login. This is especially useful when restarting FreeSWITCH™ frequently for testing purposes, since you can double click the script to run it manually when needed.

Create the Rename at Script​

A command file must be created containing the bash script statements to perform the rename function.
Start Terminal and enter this command to create the freeswitch-logren.command file in directory freeswitch-scripts:

  cp dummy.command freeswitch-logren.command

Open the file in an editor and replace the text with the following lines that will obtain the log file modification date and time, and add it to the file name:

  #!/bin/sh
  logfile="/usr/local/freeswitch/log/freeswitch.log"
  mdate=$(GetFileInfo -m $logfile)
  newname=$logfile"-"${mdate:6:4}"-"${mdate:0:2}"-"${mdate:3:2}"-"${mdate:11:2}"-"${mdate:14:2}"-last"
  mv $logfile $newname
  exit 0

Save the file, remember it's already executable.

FreeSWITCH™ can be running to test but it's preferable to shut it down so it comes up with a new log file. Double click the icon to test and check the log directory for the name change.

Setup OS X Account to Run the Rename Script​

This runs the command file every time the Desktop user logs in.

  1. Start System Preferences
  2. Click Accounts
  3. Click Logon Items
  4. Check "+"
  5. Navigate to the freeswitch-logren.command file and click Add.

Power Failure Recovery​

Most likely, you are using FreeSWITCH™ on a 24x7 Mac. In case of a power failure there are two things that should be done to maintain FreeSWITCH™ availability:

Uninterruptible Power Supply​

The Mac should be connected to a "smart" UPS that has a USB connection. This allows OS X to automatically perform a clean shutdown when there is not enough battery power to continue. OS X supports major UPS units that do not require additional software to be installed, these units are highly recommended. Once you connect the UPS via a USB cable:

  1. Start System Preferences
  2. Click Energy Saver
  3. Click UPS
  4. Set desired Computer and Screen sleep options. FreeSWITCH™ seems to do fine with sleep set.
  5. Click Shutdown Options
  6. Set the desired options based on your UPS backup time.

Auto Power Up After Failure​

If you don't have a UPS, or your UPS runs out of battery power, the Mac will shut off. If there is no one around to restart it and you want it to restart automatically follow these steps:

  1. Start System Preferences
  2. Click Energy Saver
  3. Check "Start up automatically after power failure"
  4. Click UPS
  5. Check "Start up automatically after power failure"

Email Voicemail to an iPhone​

FreeSWITCH™ invokes SENDMAIL to send voicemail as an email attachment. Fortunately, OS X comes with POSTFIX, a SENDMAIL replacement, already installed. These steps illustrate how to setup POSTFIX to send emails from OS X. Sending email does not require POSTFIX to be running, it will automatically start when required and shut down after sending email. Receiving emails require POSTFIX to be running all the time and does not apply to this document.

Setup POSTFIX​

Issue the following commands to backup the original postfix configuration file, note sudo is required:

  cd /etc/postfix
  sudo mv main.cf main.cforig
  sudo cp main.cforig main.cf
  sudo chown -R mario:staff main.cf
  sudo mv main.cf ~/Desktop

Launch Xcode as root in a Terminal window using this command, it allows editing of the configuration files:

  sudo /Applications/Xcode.app/Contents/MacOS/Xcode

Once Xcode is launched open the main.cf file to edit:

  1. Use the File/Open… menu
  2. While the file window is open press command+shift+.(period) to view hidden files.
  3. Navigate to the desktop and edit main.cf

Configure POSTFIX​

The process is not complicated but getting the settings right for your ISP may take some trial and error. The configuration below works if you have your own domain name. You can search the web for "setup outgoing email osx postfix", and if you don't have your own domain name try this link.

This is what was required to get POSTFIX working for my environment. The following lines were added to the bottom of main.cf (ISP, userid, passwords changed), also you must remove the <- comments:

myorigin = $mydomain
relayhost = [box123.greenisp.com]:26      <- domain and port of your ISP, port may be important since some block 25
myhostname = imac.yourowndomain.com   <- name of your mac and your local domain
smtp_sasl_auth_enable = no
smtp_use_tls = no
smtp_enforce_tls = no
smtp_sasl_security_options =
smtp_sasl_tls_security_options =
smtp_sasl_tls_verified_security_options =
smtp_tls_loglevel = 2
smtp_sasl_password_maps = hash:/etc/postfix/smtp_sasl_passwords
smtp_tls_per_site = hash:/etc/postfix/smtp_tls_sites
tls_random_source = dev:/dev/urandom
smtp_generic_maps = hash:/etc/postfix/generic
sudo mv ~/Desktop/main.cf /etc/postfix

sudo chown -R root:wheel smtp_sasl_passwords sudo chown -R root:wheel smtp_tls_sites

Create a file names smtp_sasl_passwords, it contains the ISP URL and a valid email address that is the email account used to send mail, an email account called "phones" was created for this purpose:

box123.greenisp.com    phones@yourowndomain.com:yourpassword    <-phones must a valid email address at the ISP

Create a file named smtp_tls_sites with the following line:

box123.greenisp.com MUST_NOPEERMATCH

Execute the following commands in Terminal:

   cd /etc/postfix
   chmod go-rx smtp_sasl_passwords
   sudo postmap smtp_sasl_passwords
   sudo postmap smtp_tls_sites
   sudo postmap generic
   sudo postfix stop
   sudo postfix start

Test and Diagnose POSTFIX​

Before trying to get FreeSWITCH™ to send email POSTFIX must be working. Running the following command in Terminal will cause an email to be sent, make sure it is a valid email address.

  printf "Subject: TestnHello" | sendmail -f you@domain.com you@domain.com

Use Xcode to view /var/log/mail.log to determine if there were problems. If there are no problems you should receive an email. Do not proceed with FreeSWITCH™ configuration until POSTFIX testing is successful.

Configure FreeSWITCH™ Email​

The information below should get email to work but you should also read the FreeSWITCH™ email documentation.

The following parameters were added to a userid in the conf/directory, note the aiff format is used since it does not require additional modules and works on the iPhone:

   <param name="vm-mailto" value="notify@yourowndomain.com"/>
   <param name="vm-email-all-messages" value="true"/>
   <param name="vm-attach-file" value="true"/>
   <param name="vm-message-ext" value="aiff"/>

   <variable name="voicemail_domain" value="yourowndomain.com"/>

Edit voicemail.xml and change the line below, make sure to use the valid email account used in the passwords file above:

Original: <param name="email-from" value="${voicemail_account}@${voicemail_domain}"/> Replacement: <param name="email-from" value="phones@yourowndomain.com"/>

This voicemail templates also required editing. Change the first line in the conf/voicemail.tpl and notify-voicemail.tpl templates:

Original: From: "${voicemail_caller_id_name}" <${voicemail_caller_id_number}@${voicemail_domain}> Replacement: From: "${voicemail_caller_id_name}" <phones@yourowndomain.com>

Our Mac sends voice emails to multiple iPhones within a few seconds. No need to wait for or miss a voicemail now!

Diagnosing Problems​

If there is a problem you may need to provide diagnostic information to the developers. Here are some options:

FreeSWITCH™ Diagnostic Tools​

There is a limited troubleshooting information page available on the wiki. However, if you report a problem you will be asked for traces and log options. It will help to have them in advance if possible so you should become familiar with some of the following debugging commands:

   reloadxml
   log 7
   console loglevel debug
   sofia loglevel all 9
   sofia profile profname(external..) siptrace on/off
   sofia status [profilename}
   sofia global siptrace on
   sofia reload
   sofia profile <name> restart
   nat_map status
   nat_map reinit
   fsctl debug_level 1

   fsctl send_sighup    # <- To force the freeswitch.log file to segment.

TCP and SIP Diagnostic Tools​

You may be asked for traces of the actual network data on the lan connection. The most common tools for this purpose are:

  • Packet trace - Find information on how to perform it on OS X here.
  • Wireshark - Great network tool to examine TCP and SIP data. Download the OS X version here. Note: You should install the Wireshark application in the Applications folder and you must run Wireshark as root so it must be run from Terminal, see line below. A "Wireshark folder" was also created to hold other Wireshark supplied items. 
sudo /Applications/Wireshark.app/Contents/MacOS/Wireshark

OS X Diagnostic Tools​

All of these tools are supplied with OS X.

  • CPU and memory utilization - Run the Activity Monitor in Applications/Utilities
  • Find source paths to running processes - Open Terminal and type the command: 
  PS -hax
  • Detailed resource usage dynamically updated - Open Terminal and type the command (-u sorts by processor utilization): 
  top  
  top -u

To terminate press control+z.

Remotely Accessing a Mac​

Setup Screen Sharing​

FreeSWITCH™ and a Mac Mini can provide PBX and other server functions while taking up almost no space since it does not require a keyboard, mouse or monitor. If you are using a Mac Mini this way or your Mac is located in a closet or other remote location you can control one Mac from another. The big bonus is that you can run Xcode and work on configurations, changes, updates, etc. all using the normal OS X screen. Perform these steps on the remote Mac to be controlled:

  1. Start System Preferences
  2. Click Sharing
  3. Check "Screen Sharing"

This Mac will now display in the Finder of other Macs on the local network. On the "controlling" Mac:

  1. Open the Finder
  2. Select the remote Mac in the SHARED section
  3. Click on "Share Screen"
  4. Enter the password for the remote Mac.

The entire Desktop of the remote Mac is displayed and controllable. It will run it as if the monitor is connected and is very fast and extremely reliable. You can even restart the remote Mac and the screen will reappear. One caveat is that sound does not play remotely. If the remote Mac is close enough turn up its volume to full to hear sounds.

Drag and Drop Files​

If you have a remote Mac running FreeSWITCH™ it may be desirable to access or transfer files between them. Starting with OS X Mountain Lion screen sharing provides drag and drop of files between screens to transfer them! No need for file transfers or other unproductive options. Nothing to setup, once screen sharing is active drag and drop is available.

Setup File Sharing​

In addition to the previously mentioned Drag and Drop, you can display file directories on a remote Mac and drag files between them. Perform these steps on the remote Mac so it can share files with other Macs:

  1. Start System Preferences
  2. Click Sharing
  3. Check "File Sharing"

This Mac will now display in the Finder of other Macs on the local network. Use the same procedure for the controlling Mac above except select "Connect" instead of "Share Screen". The directories you setup to share will display.

SSH​

If you have a headless Mac but don't have another one to use for screen or file sharing, or your only other system is Linux or Windows, you can access the remote mac via SSH. Turn on SSH access through System Preferences -> Sharing -> Remote Login. This provides limited access compared to the options above and requires knowledge of SSH usage. Simply perform a web search for "OS X SSH" to find much more information and examples.

Invisible Files and Directories​

OS X hides many Unix directories and files from the finder and Terminal app. You won't be able to view /usr or other hidden directories without special commands or extra steps. Here are some options to allow you to see hidden files:

Scripts and Widgets​

Search the web for an automator application,, applescript or program that modifies the AppleShowAllFiles finder setting. For example, OS X hiddenfiles Dashboard widget. Open Dashboard and run it to flip the setting.

Show and Hide Scripts​

Create scripts that run in the Terminal application to flip between hide and show of invisible files. The file name must end with ".command" and can be placed on the Desktop for easy access. For each of the two files below:

  1. Start Textedit
  2. Paste the lines into the empty document
  3. Pull down the Format menu
  4. Select Make Plain Text
  5. Save the file on the Desktop as -filename-

File invis show.command:

  defaults write com.apple.finder AppleShowAllFiles YES
  killall Finder

File invis hide.command:

  defaults write com.apple.finder AppleShowAllFiles NO
  killall Finder

Then run the Terminal application and issue the following commands to make the files executable:

  cd ~/Desktop    <- this is the directory where you placed the files
  chmod +x "invis show.command"
  chmod +x "invis hide.command"

Double clicking the file icons will run Terminal and change the hide/show setting.

Open Dialog Window​

While any open file dialog window is displayed press command+shift+.(period) to view hidden files. Press again to hide. Note that this does not work in the finder, only for the open dialog box while in an application such as Textedit.