About

This is the main page describing the process of installing and performing basic testing of FreeSWITCH™ and its prerequisites on OS Xpage describes FreeSWITCH™ installation methods available for the macOS releases below. It is part of the FreeSWITCH™ macOS documentation.
 ---

Introduction

If you have not read the Mac OS X page please view it now. Installation instructions are provided for OS X 10.11, 10.10 and 10.9, instructions for older releases are no longer maintained and can be found at the Mac OS X Archive.

Testing History

...

Testing Status

All macOS versions are installed into new volumes with the latest Apple Command Line Tools. Upgraded systems are never used.

...

Installation

Installation of FreeSWITCH™ on OS X can be performed using the AppleScript installer, or manually. 

AppleScript Installer

The OS X FreeSWITCH™ Installer simplifies installation of FreeSWITCH™ on OS X by automating all of the manual steps, except for prompting for an administrator password. It creates logs that are useful in case of problems. The installer can be downloaded at Installation on OS X Using AppleScript.

Manual Installation

A manual installation involves downloading and installing the following groups of software:

• Apple Xcode that provides the tools needed to generate everything else
• Prerequisite packages that FreeSWITCH™ needs to function
• FreeSWITCH™ itself

Simply Follow the steps below to perform an manual installation. There is some extra information for people who want it. If you're not too technical don't let the explanations intimidate you. Just follow the steps and FreeSWITCH™ should be installed in about an hour or two.

OS X Developer Tools

The OS X Developer Tools are composed of two parts, the Xcode OS X Software Developer Kit used to develop and test OS X GUI applications, and the Command Line Tools that provide LLVM, Clang, Git and other tools required to generate non-GUI applications such as FreeSWITCH™ and its prerequisites.

Select OS X Release

Click a link below for instructions on installing Xcode. The pages link back here to continue. 

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

Setup Installation Directories

OS X provides the /usr directory which contains subdirectories. This procedure adds the directory local to /usr as /usr/local where FreeSWITCH™ and its prerequisite source and runtime files are placed. These files are kept out of OS X supplied directories to allow easy removal of FreeSWITCH™ and its prerequisites.

Show Invisible Files and Directories in the Finder

OS X hides many Unix directories and files from the Finder including the directories created by this procedure. These files and directories can be unhidden so they appear on the desktop, Finder windows and file dialogs. Additional information and scripts for showing invisible files are in the Customization on OS X guide. View hidden files by running the lines below in Terminal:

  defaults write com.apple.finder AppleShowAllFiles YES
  killall Finder

 Create /usr Subdirectories

The user name (owner) and group name of /usr/local and it's subdirectories must match the user and group FreeSWITCH™ will run under. This is typically the main user name of the Mac. View this information (yourname and yourgroup) by running the following command in Terminal:

  ls -l ~/

The user name and group appear in the third and fourth columns. Now create the /usr/local and /usr/local/src directories, replace yourname and yourgroup with the ones obtained from the previous command:

  cd /usr                                   # Change to the /usr directory
  sudo mkdir local                          # Create the /usr/local directory
  sudo chown -R yourname:yourgroup local    # Modify the owner of the /usr/local directory to yours
  mkdir local/src                           # Create the /usr/local/src directory FreeSWITCH™ source will be downloaded into

--

Prerequisites

Prerequisite Installation Options

Additional programs are required to generate and run FreeSWITCH™. Most are installed using Homebrew, a package manager and its repository of products for OS X. Homebrew saves time since there is no need to locate packages and determine the version required for each OS X release. Homebrew's Git repository is maintained by volunteers. 

Install Package Manager and Prerequisites

Using the commands below the package manager and prerequisites install in under 10 minutes.

Install Homebrew

Homebrew installation is simple, the command can be run from any directory:

1. Go the Homebrew home page and copy the ruby command to install Homebrew.
2. Open terminal if not already opened, paste and run the command
3. Run the command "brew doctor" to verify homebrew works, this command could take a couple of minutes.

Install Required Homebrew Packages

The basic FreeSWITCH™ prerequisite packages are installed by running the following command in Terminal from any directory:

  brew install autoconf automake curl jpeg ldns libtool openssl pcre pkg-config speex sqlite

#!/bin/sh
# This script can be run asis or separated into multiple scripts, and/or edited for different directories, or run one line at a time.
# Example of how to use this script:
# 1. Create /usr/local and /usr/local/src as documented in the OS X install wiki page
# 2. Save this text on the Desktop as fssupport.command
# 3. chmod +x ~/Desktop/fssupport.command
# 4. Run command in terminal: . ~/Desktop/fssupport.command
#
# Prompts: None
#  
OS_Version=$(sw_vers -productVersion | sed "s:.[[:digit:]]*.$::g")
if [[ ${OS_Version} == 10.9 ]] | [[ ${OS_Version} == 10.10 ]] ; then   # need extra homebrew package
brew install nasm
fi
#
cd /usr/local/src
git clone https://freeswitch.org/stash/scm/sd/libflite.git
cd libflite
./configure --prefix=/usr/local
make
make install
#
cd /usr/local/src
git clone https://freeswitch.org/stash/scm/sd/libvpx.git
cd libvpx
./configure --prefix=/usr/local
make
make install
#
cd /usr/local/src
git clone https://freeswitch.org/stash/scm/sd/libyuv.git
cd libyuv
perl -pi -e s{PREFIX:=/usr}{PREFIX:=/usr/local} /usr/local/src/libyuvx/makefile
perl -pi -e s{" -m 755 "}{" "} /usr/local/src/libyuvx/makefile
perl -pi -e s{" -m 644 "}{" "} /usr/local/src/libyuvx/makefile
make
make install
#
cd /usr/local/src
git clone https://freeswitch.org/stash/scm/sd/opus.git
cd opus
./autogen.sh
./configure --prefix=/usr/local
make
make install
exit 0

Download FreeSWITCH™

OS X is now ready to download and install FreeSWITCH™.

Selecting a Version

There are two versions of FreeSWITCH™ to choose from: the current release version recommended for production systems, and master containing the latest fixes and features used during development. The current release version is recommended unless you need newer features or patches added since the current release of FreeSWITCH™. Additional Information is located at Source Options.

This documentation is tested with the master version to keep it as recent as possible and to provide feedback to the developers. If there are problems the developers may request that you install the master version for diagnosis.

Download Using Git Clone

Download FreeSWITCH™ by switching to the src directory and invoking one of the "git clone" commands below.  The git command will create the freeswitch directory in src  (/usr/local/src/freeswitch) and download the FreeSWITCH™ source files.

  cd /usr/local/src
  git clone -b v1.6 https://stash.freeswitch.org/scm/fs/freeswitch.git             # The current production release version
        or
  git clone https://stash.freeswitch.org/scm/fs/freeswitch.git                     # The master/development version

Install FreeSWITCH™

Generate Installation and Configuration Files

This step creates installation files based on the operating system and installed packages. ./bootstrap.sh creates many files such as modules.conf used to add optional functionality to FreeSWITCH™, while ./configure sets compilation options. Enter the following commands (each will run several minutes):

  cd freeswitch    # <- the new freeswitch directory created by the git clone process
  ./bootstrap.sh
  ./configure

Add Text–To–Speech Module

Optional functions are added to FreeSWITCH™ by editing the modules.conf file, this may be required as your FreeSWITCH™ configuration becomes more complex. Although not required, adding FLITE Text To Speech functionality is recommended. The easiest way to add the FLITE module is to paste and run the following line into Terminal:

   perl -pi -e 's{#asr_tts/mod_flite}{asr_tts/mod_flite}' /usr/local/src/freeswitch/modules.conf

If you prefer to manually edit the modules.conf file use this procedure:

1. Use the Finder to navigate to the /usr/local/src/freeswitch directory.
2. Scroll to and double-click modules.conf in the freeswitch directory, the first time requires application selection, Textedit should be used.
3. Search for "flite" and remove the # to uncomment.
4. Save the file.

This step compiles the programs and creates additional directories and files based on modules.conf. It can run longer than 10 minutes. While still in /usr/local/src/freeswitch compile FreeSWITCH™ with the following command:

  make

If there are no errors proceed, otherwise seek assistance from the FreeSWITCH-users mailing list

Generate FreeSWITCH™ Runtime

This creates the /usr/local/freeswitch runtime library and executable programs.

  make install

Download and Install Sounds

There are mandatory sound prompts and optional music on hold files. All must be downloaded to run the sample IVR. There are four versions available:

• sounds-install moh-install (8 kHz)
• hd-sounds-install hd-moh-install (16 kHz)
• uhd-sounds-install uhd-moh-install (32 kHz)
• cd-sounds-install cd-moh-install (48 kHz)

The cd sounds are recommended since all the sampling rates are provided resulting in fewer problems. Invoke the following command:

  make cd-sounds-install cd-moh-install

Cleanup

This optional step can be performed to save space by removing the temporary files created by make:

  make clean

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?

Updating

Updating FreeSWITCH™

FreeSWITCH™ may occasionally require updating due to new features, fixes, etc. To download the latest updates, compile FreeSWITCH™ and create updated runtime binaries, run the following two commands:

  cd /usr/local/src/freeswitch
  git pull && make current

Updating Prerequisites

To update Homebrew and its formulas run "brew update" in Terminal, this should be run prior to upgrading packages. To upgrade all packages, run "brew upgrade", or to upgrade a single package run "brew upgrade package-name" command.

Removal

Removing FreeSWITCH™

Consider backing up modified or new configuration files you created! FreeSWITCH™ is completely removed by deleting the /usr/local/freeswitch and /usr/local/src/freeswitch directories using the Finder (drag to trash) or in Terminal:

  rm -r /usr/local/freeswitch
  rm -r /usr/local/src/freeswitch

Remove Homebrew and Prerequisites

Packages installed by Homebrew are listed using the "brew list" command. They are removed using the "brew uninstall package-name" command. To remove packages and Homebrew run the following in Terminal:

rm -rf /usr/local/Cellar /usr/local/.git && brew cleanup
sudo rm -r /Library/Caches/Homebrew   # (OS X prompts for the administrator password)

If the /usr/local directory existed prior to using this procedure it has to be examined to determine if the contents are deletable. If the instructions on this page were followed, and the /usr/local directory was created during this procedure, everything can be removed to roll back the system prior to using this procedure by performing these steps:

1. Drag everything in the /usr/local directory to the trash. Or delete it in Terminal (OS X prompts for the administrator password):

  sudo rm -r /usr/local/*

Hide Invisible Files and Directories in the Finder

To reverse the show hidden files step, open the Terminal application and run each line below. All hidden files will disappear from the desktop, Finder and file dialogs.

Warnings About Upgraded Systems

Systems that were upgraded from older software may have issues due to old parts of a prior OS X or Xcode still intact. In these cases a fresh OS X and Xcode install may required.

...

Upgraded OS X?
Most upgraded OS X systems work depending on the level of the oldest original system. Systems upgraded from 10.7 or older may have problems due to old files left in various directories. 

Upgraded Xcode?
Most upgraded Xcode systems will work depending on the level of the oldest original Xcode. Xcode upgraded from version 4 or earlier may have problems.

Preparation

Backup!

This procedure installs a significant amount of software, all of it can be removed using the procedures at the bottom of this page. However, there may be times when parts of the Apple Command Line Tools, part of Xcode may remain. Although there is no problem leaving the CLT installed, If you want to remove them it's best to backup before starting this procedure.

Terminal Application Preferences

We'll use the Terminal application extensively during installation and to start FreeSWITCH™ initially. You should make the following changes to save time during this procedure:

...

...

Installation Methods

...