Call Us Today! 877.742.2583




Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

About

This page section describes the process of installing and performing basic testing of FreeSWITCH™ and its prerequisites on macOS 10.12, OS X 10.11, and 10.10. Instructions for older releases are located at the Mac OS X Archive.
 ---

Panel
bgColor#f8f8f8

Table of Contents
outlinetrue
excludeAbout
stylenone

Testing History

Testing is performed on clean installs of macOS, not upgraded from a prior macOS release.

Section
Column
width6%

 

Column
width50%

                                                    macOS FreeSWITCH™ Testing History

ReleaseTestedXcodeFreeSWITCH™ VersionStatus

10.12.3 Sierra

January 12March 9, 2017

 February 4, 2017

8.2.1

1.6.1415+git~20170112 git~20170309 Production Release

1.9.0+git~20170204 Master Development

Good

Good

  10.11.6 El Capitan

March 4, 2017

March 4, 2017

7.3.1

1.6.15+git~20170303 Production Release

1.9.0+git~20170304 Master Development

Good

Good

  10.10.5 Yosemite

March 4, 2017

March 4, 2017

7.2.1

1.6.15+git~20170303 Production Release

1.9.0+git~20170304 Master Development

Good

Good

 

 


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 some of the Apple Command Line Tools, part of Xcode may remain. Although there There is no problem leaving the CLT these small parts installed, If you want to remove them it's best to backup but to restore to a point where nothing was installed a backup is required before starting this procedure.

Terminal Application Preferences

The Terminal application is used extensively during installation, and to start FreeSWITCH™. The following changes are recommended to save time:

  1. Copy Terminal in the Applications/Utilities folder into the Dock for quick access.
  2. Start the Terminal application by clicking it in the dock. Then open its preferences panel.
  3. In Settings–>Profiles–>Window change the Window Size to larger values such as 140x48 to reduce having to resize the window often.
  4. In Settings–>Profiles–>Window set Scrollback to "Limit to Available Memory" or a larger number. Many messages are produced that may be needed for problem analysis.
  5. In Settings–>Profiles–>Shell set Prompt before closing to "Only if there are processes other than:". This prevents the Terminal window from closing when FreeSWITCH™ is shutdown if it started automatically, which would result in the loss of all messages in the window. This is useful during debugging. If FreeSWITCH™ started manually the window does not close.
Warnings About Older Upgraded Systems

 


 

Warning
titleWarning - Very Old Upgraded Systems

Upgraded macOS or Xcode?
Upgraded

macOS

systems that originally contained 10.7 Lion or older, or Xcode version 4 or older, will likely have significant problems.

 In these cases a clean macOS and Xcode install is required.

Prerequisites Previously Installed Differently?

If prerequisites were previously installed using methods other than described here, there may be problems.

 

Installation Methods

Installation of FreeSWITCH™ on macOS can be performed using the macOS FreeSWITCH™ Installer (macFI), or manually.

macOS FreeSWITCH™ Installer (macFI)

The macOS FreeSWITCH™ Installer is the recommended method since it simplifies installation of FreeSWITCH™ by automating all of the manual steps. It also creates logs which are very useful if a problem occursAside from being much faster, other advantages include renaming existing FreeSWITCH™ directories before installation, and creating installation logs. The macFI can be downloaded at macOS macFI Installation.

Tip

The macOS FreeSWITCH™ Installer performs the identical functions as a manual install with a few additions such as logging.

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 a manual installation. There's extra information for people who want it. If you're not very technical don't let the explanations intimidate you. Just follow the steps and FreeSWITCH™ should be installed in an hour or two.

     

    macOS Developer Tools

    ...

    ,

    ...

    Download Xcode

    Xcode takes a while to download and is placed into the Applications folder (/Applications directory) with the Command Line Tools in /Applications/Xcode.app/Contents/Developer.

    Sierra 10.12:  install Xcode 8 using the macOS App Store application then start Xcode.
    These Xcode Downloads require you to sign in with your Apple ID and agree to the Software Agreement: 
    El Capitan 10.11:  download and install Xcode 7.3.1 from Xcode 7.3.1 Download then start Xcode.  NOTE: Xcode 8 CANNOT be used. See FS-9521.
    Yosemite 10.10:   download and install Xcode 7.2.1 from Xcode 7.2.1 Download then start Xcode. Perform Rename Xcode Directory (As of Xcode 7.1).

    Complete Xcode Installation

    Important: To complete installation of Xcode it must be started once to accept the license agreement and install the final components.

      

    Setup Installation Directories

    macOS 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 macOS supplied directories to allow easy removal of FreeSWITCH™ and its prerequisites.

    Show Invisible Files and Directories in the Finder

    macOS 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 macOS Customization guide. View hidden files by running the lines below in Terminal:

    Code Block
      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:

    Code Block
      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:

    Code Block
      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
    Tip

    You will access /usr/local often so it should be placed in the Finder "FAVORITES" sidebar for quick access. Navigate to the /usr/local folder in the Finder, then drag the local folder under "FAVORITES".

    Extra info: Even though macOS did not contain the /usr/local directory, /usr/local/bin is defined at the end of the default macOS path. The path is viewed by running "echo $PATH" in Terminal. If you don't understand this, don't worry, it doesn't affect anything.

    --

    Warning

    NEVER delete the local directory in /usr after it's created! It's very difficult to recreate, it must be restored from a backup. This is due to System Integrity Protection (aka rootless) security starting with OS X 10.11.

     

    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 macOS. Homebrew saves time since there is no need to locate packages and determine the version required for each macOS release. Homebrew's Git repository is maintained by volunteers. 

    Install Package Manager and Prerequisites

    The Homebrew package manager and prerequisites install in approximately 10 to 15 minutes.

    Install Homebrew

    Homebrew installation is simple, the install command is found at the Homebrew home page and is listed below.

    1. Open Terminal if not already opened, paste and run the ruby command from any directory.
    2. Run the command "brew doctor" to verify homebrew works, this command could take a couple of minutes.
    Code Block
    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    brew doctor

    Install Required Homebrew Packages

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

    Code Block
    brew install autoconf automake curl FreeSWITCH/homebrew-freeswitch/flite jpeg ldns libsndfile libtool lua openssl opus pcre pkg-config speex speexdsp sqlite yasm
    
    Note
    Some packages produce keg-only messages which can be ignored. It means an alias (link) for the package was not placed into /usr/local/bin because brew found that macOS has another version installed. This is not a problem because the FreeSWITCH™ installation process searches Homebrew directories to find package.

     

    Download FreeSWITCH™

    macOS 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 creates the freeswitch directory in src  (/usr/local/src/freeswitch) and downloads the FreeSWITCH™ source files.

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

     

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

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

    Add Text–To–Speech Module

    Additional functionality may be required as your FreeSWITCH™ needs become more complex. Optional modules are used to add new functions to FreeSWITCH™ by editing the modules.conf file. The FLITE Text To Speech functionality is recommended for a new system since some of the sample tests require it. The easiest way to add the FLITE module is to paste and run the following line into Terminal:

    Code Block
       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.

     

    Warning

    If this is your first FreeSWITCH™ don't add more than the FLITE module. Some modules may have prerequisites in addition to what is listed in this procedure.

     

    Compile, Create Additional Source Directories and Check for Errors

    This step compiles the programs and creates additional directories and files based on modules.conf. While still in /usr/local/src/freeswitch compile FreeSWITCH™ with the "make" command, it runs for several minutes:

    Code Block
      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.

    Code Block
      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:

    Code Block
      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:

    Code Block
      make clean

    Test FreeSWITCH™!

    Startup From the Command Line

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

    Code Block
      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:

    Code Block
      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 macOS 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 CallsTest as many functions as you can to experience the potential of FreeSWITCH™.

    Shutdown FreeSWITCH™

    Issue the following command in the FreeSWITCH™ Terminal window:

    Code Block
      shutdown

     

    What Next?

    Once FreeSWITCH™ has been tested it's time to customize macOS. The macOS Customization instructions will keep you busy!

    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:

    Code Block
      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:

    Code Block
      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:

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

     

    Remove Xcode

    Xcode is installed as an macOS package (directory) that looks like a single application file. To remove Xcode drag the application to the trash, empty it and restart macOS.

    Remove Everything Else

    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 (macOS prompts for the administrator password):
    Code Block
      sudo rm -r /usr/local/*
    Warning

    If using OS X 10.11 El Capitan or later: NEVER delete the local directory in /usr after it's created! It's very difficult to recreate, it must be restored from a backup. This is due to System Integrity Protection (aka rootless) security starting with OS X 10.11.

    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.

    ...

    prerequisites and FreeSWITCH™ by entering commands into the Terminal application.

    To perform a manual installation use the macOS Manual Installation instructions,

     

    ...