Deploy Aternity Agent for Mac to Multiple Apple Macs

Mass-deploy the Agent for Mac to all the Macs you want to monitor in your enterprise. The Agent for End User Devices monitors end user experience by measuring device and application performance.

To mass distribute a rollout of the Agent for Mac, use the same setup pkg file in the command line, by adding it to a script in your deployment system.

The Agent for Mac is a standard macOS daemon with no visible change to the screen or menu bar.

Deploy Agent for End User Devices with your software distribution system

Before you begin

Verify you have Google Chrome on your computer. Agent for Mac requires Google Chrome for the setup to succeed. If not installed, the Agent for Mac setup will fail when trying to install Chrome extensions.

You must be familiar with your Mac distribution or management tool, like JAMF Pro, Puppet, Airwatch, Microsoft SCCM, Munki or other tool, and that you can adapt the setup script to fit your environment.

Install the Agent for Mac on a single Apple Mac or small set of computers to try Aternity's monitoring on Macs (learn more).

To monitor an Apple Mac with Aternity Agent for Mac, it must have the following minimum system requirements:

Attribute Requirement
Agent for Mac

Supported versions of Agent for Mac: 2.4, 3.0, 3.1.x, 3.2.x

Mac operating system

macOS 10.14 (Mojave) (since version 3.1), macOS 10.13 (High Sierra) (since version 2.4), macOS 10.12 (Sierra), OS X 10.11 (El Capitan), or OS X 10.10 (Yosemite)

Processor

Mac computer with Intel 64-bit CPU.

Resource usage

The Agent for Mac typically uses:

  • CPU: Total utilization across all cores less than 1%.

  • RAM: The Aternity Agent for Mac uses approx. 200-300MB of physical memory.

  • Storage: At least 0.5GB free disk space available.
  • Bandwidth: Network traffic load overhead increases by approx. 0.02 kilobytes per second (KBps) incoming to the device, and approx. 0.05KBps reporting data to Aternity.

Monitor web applications

Monitor any web application in any version of Google Chrome released in the past two years. For legacy Agents (on Windows until Agent 9.1.x or on Mac until Agent for Mac 2.3), you must also manually add the Aternity Extension for Chrome to monitor web page load events (WPM) and usage.

Procedure

  1. Step 1 Download and launch the Agent setup directly from Aternity.

    This Agent is already customized for your enterprise. Learn more.

    The setup package and the extracted Agent files are secure, signed with our certificate. After you set up the Agent, it can communicate securely with the server using the HTTPS protocol on port 443. Learn more about security.

    Select the type of setup to download
  2. Step 2 Test the command line setup in the Terminal window of a single Mac, to determine the parameters you need for the mass-deployment of Agent for Mac.
    1. a Open the Terminal command line window by selecting Applications > Utilities > Terminal.
    2. b Navigate to the directory with the pkg file.
    3. c To run the pkg file in the Terminal window, use the standard installer command.

      In the directory of the pkg file, enter:

      installer -pkg mac-agent.pkg -target CurrentUserHomeDirectory
      Field Description
      -pkg

      Enter the source pathname of the pkg file.

      -target

      Enter CurrentUserHomeDirectory and the Agent will be installed in this user home directory.

      -verboseR

      (Recommended) Use this parameter to create a log of the setup on this device to keep track of any errors. The extra R indicates to format the log for easy parsing.

      -dumplog

      (Recommended) Routes the log output in the system log to the standard output (Terminal window). For mass distribution, this forwards the log output to the distribution system's logs, which you can use to troubleshoot problems.

  3. Step 3 Open your mass-distribution tool for Macs.

    We tested with JAMF Pro, but these instructions cover any distribution system which is compatible with Macs, like Puppet, Airwatch, Microsoft SCCM, Munki or other tool, where you can adapt the script to fit your environment.

  4. Step 4 Create a new deployment in your mass distribution system.
  5. Step 5 Create a script which sets up the Agent for Mac in the user's home directory.

    Perform the setup as a local user in the Terminal window on each computer, by calling installer from su -l <username> -c. Do NOT use sudo -u. Then add the same parameters which you tested earlier on a single Mac:

    su -l $current_user -c "installer <parameters>"

    A typical mass-deployment script would be similar to the following:

    #!/bin/bash
    
    #Get the current user on a device. Notice the back-quote for embedding the python script.
    this_user=`python -c 'from SystemConfiguration import SCDynamicStoreCopyConsoleUser;\
    	   import sys;\
    	   username = (SCDynamicStoreCopyConsoleUser(None, None, None) or [None])[0];\
    	   username = [username,""][username in [u"loginwindow", None, u""]];\
    	   sys.stdout.write(username);'`
    
    # Copy the Agent pkg file to the home or shared directory of the user.
    # Use the copy method for your distribution system.
    
    #Set up the pkg file with full logs, placing the Agent files in the home directory of the user.
    su -l $this_user -c "/usr/sbin/installer -verboseR -dumplog -pkg /Users/$this_user/mac-agent.pkg -target CurrentUserHomeDirectory"
    
    Field Description
    $current_user

    Find the current user of this Mac.

    Important

    The Agent for Mac must set up as the current signed in user, NOT at the system level.

    cp

    This parameter copies the pkg file to a location where the local user can access it, like the user's home directory or shared directory.

    Tip

    In JAMF Pro, you can only do this by creating a package of the pkg file (using Casper Composer), and then setting up (unpacking) it to the user's home directory. This in effect copies the original pkg file to the user's home directory.

    For details on how to do this in your distribution system, contact your vendor's support.

    su -l $current_user -c

    Perform this action as the signed in user in the console (Terminal window):

    su -l username runs a command as a specified signed in user.

    su -c runs a command in the console (Terminal window).

    Important

    Only su -l -c ensures you perform the installer command on the console as the signed in user.

    Do NOT use sudo -u.

    installer

    Use this standard command line (Terminal) setup application to deploy the Agent for Mac automatically.

    -pkg

    Enter the source pathname of the pkg file.

    -target

    Enter CurrentUserHomeDirectory and the Agent will be installed in this user home directory.

    -verboseR

    (Recommended) Use this parameter to create a log of the setup on this device to keep track of any errors. The extra R indicates to format the log for easy parsing.

    -dumplog

    (Recommended) Routes the log output in the system log to the standard output (Terminal window). For mass distribution, this forwards the log output to the distribution system's logs, which you can use to troubleshoot problems.

  6. Step 6 Set the conditions when the script runs on a Mac.
    • Run the script once per computer. If a computer has more than one user, run the script once per user on each computer.

      Note

      Note that even if a computer has more than one user, only one active login is allowed, meaning one user can be active at a given time, and other users must be logged off. Otherwise, you may see duplicated reports for device resources or experience other performance issues.

    • You do NOT need to restart the computer.

    • Choose the trigger event which launches the script, to match the policies of your enterprise. We recommend performing the script on each computer as soon as possible. Avoid waiting for a restart, as some users do not reboot their Macs often.

  7. Step 7 Verify the deployment was successful.
    1. a Check the deployment status by inspecting the logs of your distribution system to ensure they completed successfully on each computer.
    2. b Open a browser and sign in to Aternity.
    3. c Select the device icon in the top bar of any dashboard to view details of your computer.
      Verify the number of monitored devices
  8. Step 8 To monitor web applications running in the Chrome browser, deploy the Aternity Extension for Chrome.

    To mass-deploy the extension without requiring users to manually enable the extension, run install_chrome_ext (part of the Agent download) with administrator privileges on each Mac device:

    sudo ./install_chrome_ext

    It starts to monitor web applications in Chrome only after the user restarts Chrome.

    Tip

    If the device cannot access the Chrome Web store or if it is not part of the enterprise domain, you can deploy it manually (learn more).

    Note

    Agent for Mac 3.0 uses Aternity Extension for Chrome 9.2.2. Agent for Mac 3.1 and 3.2 use Aternity Extension for Chrome 9.2.5.