Difference between revisions of "Installation and Setup on OS X"

From FreeSWITCH Wiki
Jump to: navigation, search
(update test dates, remove backup/prep, start major updates)
Line 1: Line 1:
 +
<br><br><br>
 +
'''This page and other OS X [ages have had major update and were converted to Confluence April 28 2014, it will no longer be updated but is still accurate. It is located at:
 +
https://confluence.freeswitch.org/display/FREESWITCH/Installation+and+Setup+on+OS+X
 +
<br><br><br>
 +
__TOC__
 +
 
==Introduction==
 
==Introduction==
 
'''What Can You Do With FreeSWITCH™? '''<br/>
 
'''What Can You Do With FreeSWITCH™? '''<br/>
Line 35: Line 41:
 
! scope="col" width="150px" | Release !! Tested !! Installation Wiki Page
 
! scope="col" width="150px" | Release !! Tested !! Installation Wiki Page
 
|-
 
|-
| &nbsp; 10.9.2 Mavericks    || &nbsp; April 9, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.9_Mavericks Installation on OS X 10.9 Mavericks ] &nbsp;  
+
| &nbsp; 10.9.2 Mavericks    || &nbsp; April 28, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.9_Mavericks Installation on OS X 10.9 Mavericks ] &nbsp;  
 
|-
 
|-
| &nbsp; 10.8.5 Mountain Lion    || &nbsp; April 9, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.8_Mountain_Lion Installation on OS X 10.8 Mountain Lion ] &nbsp;  
+
| &nbsp; 10.8.5 Mountain Lion    || &nbsp; April 26, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.8_Mountain_Lion Installation on OS X 10.8 Mountain Lion ] &nbsp;  
 
|-
 
|-
| &nbsp; 10.7.5 Lion    || &nbsp; April 9, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.7_Lion Installation on OS X 10.7 Lion ] &nbsp;  
+
| &nbsp; 10.7.5 Lion    || &nbsp; April 26, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.7_Lion Installation on OS X 10.7 Lion ] &nbsp;  
 
|-
 
|-
| &nbsp; 10.6.8 Snow Leopard    || &nbsp; April 9, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.6_Snow_Leopard Installation on OS X 10.6 Snow Leopard ] &nbsp;  
+
| &nbsp; 10.6.8 Snow Leopard    || &nbsp; April 26, 2014 &nbsp;  || &nbsp;&nbsp;[http://wiki.freeswitch.org/wiki/Installation_on_OS_X_10.6_Snow_Leopard Installation on OS X 10.6 Snow Leopard ] &nbsp;  
 
|}
 
|}
 
{{warning|content=
 
{{warning|content=

Revision as of 18:56, 28 April 2014




This page and other OS X [ages have had major update and were converted to Confluence April 28 2014, it will no longer be updated but is still accurate. It is located at: https://confluence.freeswitch.org/display/FREESWITCH/Installation+and+Setup+on+OS+X


Contents


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.

Informational Tip

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 9, 2014


 

Installation

Select OS X Release

Click a link below to view instructions for installing FreeSWITCH™ on each OS X release. The pages link back here to continue.

FreeSWITCH™ OS X Release Status
Release Tested Installation Wiki Page
  10.9.2 Mavericks   April 28, 2014     Installation on OS X 10.9 Mavericks  
  10.8.5 Mountain Lion   April 26, 2014     Installation on OS X 10.8 Mountain Lion  
  10.7.5 Lion   April 26, 2014     Installation on OS X 10.7 Lion  
  10.6.8 Snow Leopard   April 26, 2014     Installation on OS X 10.6 Snow Leopard  
Warning

Using an Upgraded OS X or Xcode
All testing was performed with a clean OS X and Xcode installed, in all cases FreeSWITCH™ installation using these instructions occurred without issues. In most cases, an upgraded OS X or Xcode will work, however, there have been some reports where an upgraded OS X or Xcode caused problems due to old files left in different directories. Keep this in mind if you have problems.

 

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 Using the Sample Configuration

FreeSWITCH™ comes with a sample configuration that you can use to test with immediately. You can test using a physical SIP phone or softphone such as those found on the OS X App Store, search for SIP and try a free download such as Telephone. The most sophisticated is Bria. To setup a phone and test some functions view Some stuff to try out. The IP address of FreeSWITCH™ is the address of the Mac it is installed on. 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 the Getting Started Guide and "poke around" 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.

Informational Tip

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/*    <– Adding the -r (recursive) option will include all subdirectories in the search.

 


Setting Up 24x7 Operation

Create Dummy Script File

Informational Tip

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 can be created in Textedit or Xcode but creating a simple text file in them takes extra steps. The permission must also be changed for command files to become executable. Rather than repeat this process for each file, we will create a dummy command file that will serve as a skeleton and retain its permissions when copied as needed. 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

Now make sure they are saved as text:

  1. Pull down the Format menu
  2. Select Make Plain Text
  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.

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

#!/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 down 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
   Backup other files you plan to change

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

To force the freeswitch.log file to segment:

   fsctl send_sighup

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.

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.

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:

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.