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

About

This section describes how to prepare macOS for running FreeSWITCH™ 24x7. It is part of the FreeSWITCH™ macOS documentation.

 

Why 24x7 Operation?

Once all of the FreeSWITCH™ configuration is completed and phones are in place, macOS must be prepared so that FreeSWITCH™ is always started and kept running. If the Mac is restarted intentionally, or macOS is restarted for any reason, such as a crash, you'll want the phone system up and running as fast as possible. These instructions illustrate how to prepare macOS so that FreeSWITCH™ is automatically restarted under those conditions.

You can perform all editing using Textedit, however, you should become familiar with the Xcode editor. Its advantage is that it displays XML code colorized so you can find syntax errors quickly. This is ideal for editing FreeSWITCH™ XML configuration files.

 

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

  1. Start Textedit
  2. Paste the two lines below into the empty document:

Make sure they are saved as text:

  1. Pull down the Format menu
  2. Select Make Plain Text,  if the default for saving text is already Plain Text, this step is not needed.
  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.
  4. 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:

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


Open the freeswitch.command file in the editor and replace the two lines with the following bash script:

 

 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 macOS 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 macOS, only two are covered here. Both are the current recommended methods for automatically starting programs on macOS. 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 macOS 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 macOS Launchd daemon can be used to start FreeSWITCH™ when macOS 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

 

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:

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:

 

Or from Terminal either of these commands would work from the freeswitch/bin directory:

Shutdown Using Launchd

The macOS Launchd daemon can be also be used to shutdown FreeSWITCH™. This is not needed during macOS shutdown because macOS 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:


Open the file in the editor and add the following line as the second line of the file (between the existing two lines):

 

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

 

You can either restart the Mac or issue the following command to activate the 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 macOS 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:


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

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


Open the file in the editor and add the following line as the second line of the file (between the existing two lines).

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

 

You can either restart the Mac or issue the following command to activate the 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:


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.

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

 

You can either restart the Mac or issue the following command to activate the 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 Rename 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:


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:

 

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 macOS 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 macOS to automatically perform a clean shutdown when there is not enough battery power to continue. macOS 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"
  • No labels