Call Us Today! 877.742.2583




Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 14 Next »

About

This page describes the process of installing, updating and removing FreeSWITCH™ and its prerequisites on macOS using the Terminal application instead of the macFI. This page is part of the FreeSWITCH™ macOS documentation.
 ---

Knowledge

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

New To You
A new folder (directory) named /usr/local, it's part of the Linux/UNIX standard directories. We'll also use the Linux/Unix commands: cdmkdirlscpmv,chmodchown, and sudo. You don't need to learn about them unless you change the steps or directories used in this document.

 


Overview

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. It takes about two hours to have the sample FreeSWITCH™ configuration running on macOS.
 


Preparation

Terminal Application Preferences

The Terminal application is used extensively during installation. The following changes are highly recommended:

  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.
     

macOS Developer Tools

The macOS Developer Tools are composed of two parts, the Xcode macOS Software Developer Kit used to develop and test macOS GUI applications, and the Command Line Tools that provide LLVMClangGit and other tools required to generate non-GUI applications such as FreeSWITCH™ and its prerequisites. The Command Line Tools are included with Xcode. The Apple Developer site offers the standalone CLT but it cannot be used because Homebrew will not install without the Xcode/CLT version.

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.

  


Installation Directories

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 must 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:
  defaults write com.apple.finder AppleShowAllFiles YES
  killall Finder

Directories Overview and Security

macOS provides the /usr directory which contains the subdirectory local as /usr/local, this procedure will add the following subdirectories:

  • FreeSWITCH™  source located in /usr/local/src
  • FreeSWITCH™  runtime located in /usr/local/freeswitch
  • FreeSWITCH™  prerequisite source and runtime files located in several additional directories.

These files are kept out of macOS supplied directories to allow easy removal of FreeSWITCH™ and its prerequisites.

The /usr/local directory is protected and cannot be removed. Any modification to /usr/local such as adding or removing subdirectories requires administrator authority. The new subdirectories can have their security changed so that non-administrators can modify them. 

Create /usr/local Subdirectories

The /usr/local subdirectory is not supplied by OS X 10.10 Yosemite so it must be created by running the following commands in Terminal, sudo will prompt for the administrator password:

  cd /usr
  sudo mkdir local                          # Create the /usr/local directory

The user name (owner) and group name of the /usr/local subdirectories created by this procedure must match the user and group FreeSWITCH™ will run under. This is typically the main user name of the Mac. Use the mkdir command to create the freeswitch and src directories and the chown command to change the owner. Copy/paste these commands in Terminal, sudo will prompt for the administrator password:

  cd /usr/local                             # Change to the /usr/local directory
  sudo mkdir freeswitch src                 # Create the FreeSWITCH™ runtime and source directories
  sudo chown -R `id -u`:`id -g` freeswitch src  # Change the owner of the two new directories to yours

If you would like to see the ownership and permissions of directories and files use the "ls -l" command in Terminal.

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: /usr/local/bin is defined in 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.

--

NEVER delete the /usr/local directory! 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.
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 (copy/paste) in Terminal from any directory:

brew install autoconf automake curl FreeSWITCH/homebrew-freeswitch/flite jpeg ldns libsndfile libtiff libtool lua openssl opus pcre pkg-config speex speexdsp sqlite yasm
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.

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

  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:

   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.

 

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:

  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™!

The time has come to start and test FreeSWITCH™ using the macOS Testing and Diagnostics instructions.


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   # (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):
  sudo rm -r /usr/local/*

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.

  defaults write com.apple.finder AppleShowAllFiles NO
  killall Finder
  • No labels