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:
- 1 Archived Page
- 2 Introduction
- 3 Installation
- 4 Test FreeSWITCH™!
- 5 What Next?
- 6 Setting Up 24x7 Operation
- 6.1 OS X Maximum Number of Open Files Limit
- 6.2 Create Dummy Command File
- 6.3 Create the FreeSWITCH™ Command Script
- 6.4 Automatic Startup and Shutdown
- 6.4.1 Autostart Using Login Items
- 6.4.1.1 Setup OS X Account to Autostart FreeSWITCH™
- 6.4.2 Autostart Using Launchd
- 6.4.2.1 Create the FreeSWITCH™ plist
- 6.4.2.2 Test the FreeSWITCH™ plist
- 6.4.2.1 Create the FreeSWITCH™ plist
- 6.4.3 Shutdown Using Launchd
- 6.4.3.1 Create Shutdown Script
- 6.4.3.2 Create Shutdown plist
- 6.4.3.1 Create Shutdown Script
- 6.4.4 Diagnosing plist Problems
- 6.4.5 Create A freeswitch-CLI Command Script
- 6.4.1 Autostart Using Login Items
- 6.5 Log Segmentation and Clearing
- 6.5.1 Automatic Log Segmentation
- 6.5.1.1 Create Log Segment Script
- 6.5.1.2 Create Log Segment plist
- 6.5.1.3 Automatic Log Clearing
- 6.5.1.4 Create Log Clear Script
- 6.5.1.5 Create Log Clear plist
- 6.5.1.6 Automatic Log Rename at Login
- 6.5.1.7 Create the Rename at Script
- 6.5.1.8 Setup OS X Account to Run the Rename Script
- 6.5.1.3 Automatic Log Clearing
- 6.5.1.2 Create Log Segment plist
- 6.5.1.1 Create Log Segment Script
- 6.5.1 Automatic Log Segmentation
- 6.6 Power Failure Recovery
- 7 Email Voicemail to an iPhone
- 7.1 Setup POSTFIX
- 7.1.1 Configure POSTFIX
- 7.2 Configure FreeSWITCH™ Email
- 7.1 Setup POSTFIX
- 8 Diagnosing Problems
- 9 Remotely Accessing a Mac
- 9.1 Setup Screen Sharing
- 9.1.1 Drag and Drop Files
- 9.2 Setup File Sharing
- 9.3 SSH
- 9.1 Setup Screen Sharing
- 10 Invisible Files and Directories
- 10.1 Scripts and Widgets
- 10.2 Show and Hide Scripts
- 10.3 Open Dialog Window
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
Release | Tested | Installation Wiki Page |
---|---|---|
10.11.0 El Capitan | October 3, 2015 | Installation on OS X 10.11 El Capitan |
10.10.5 Yosemite | October 3, 2015 | Installation on OS X 10.10 Yosemite |
10.9.5 Mavericks | October 3, 2015 | Installation on OS X 10.9 Mavericks |
Mac OS X Archive | MacOS 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:
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>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.sudo chmod 644 ~/Desktop/limit.maxfiles.plistsudo chown -R root:wheel ~/Desktop/limit.maxfiles.plistsudo 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
- Start Textedit
- Paste the two lines below into the empty document:
#!/bin/bash
exit 0
Make sure they are saved as text:
-
Pull down the Format menu
-
Select Make Plain Text, if the default for saving text is already Plain Text, this step is not needed.
-
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):
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.
- Start System Preferences
- Click Accounts
- Click Logon Items
- Check "+"
- 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
- Start Textedit
- Paste the lines below into the empty document
- Pull down the Format menu
- Select Make Plain Text
- 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:
- Test your phones
- Launch Activity Monitor
- 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:
- Start Textedit
- Paste the lines below into the empty document
- Pull down the Format menu
- Select Make Plain Text
- 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)
- 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.