TABLE OF CONTENTS


1. Introduction


The Backdrop macOS client is a cluster of applications that runs a number of system and user processes.


Once installed and enrolled it provides students with the freedom to explore the internet while empowering teachers to monitor, guide, and assist. The macOS client shares a live stream of the student's device with the teacher and allows them to perform the following actions. 


Classroom

  • Send Message – Teachers can send a direct one-way message to the device 
  • Launch Website – Teachers can open a website on the device automatically 
  • Lock Screens – Teachers can lock the screen of the device
  • Internet Access – Teachers can disable internet access in browsers where Impero browser extensions are installed
  • Website Lists – Teachers can enforce allow and block website lists in browsers where Impero browser extensions are installed
  • Close Application - Teachers can view a list of open applications on the device and can force them to close
  • Close Tab – Teachers can view open browser tabs lists and close open tabs in browsers where Impero browser extensions are installed
  • Broadcast Screen - Teachers can broadcast their screen to students or broadcast student to student
  • Logout Device - Teachers can remotely log out of the Windows device. This returns the student to the Windows login screen and disconnects them from Backdrop
  • Google Meets - Teachers can invite the class to a Google Meets session that opens automatically on student devices
  • Switch Schools - The Backdrop client has the capability for students to be registered against multiple schools

Wellbeing

  • Written words - Monitors typed words and sends captures to Backdrop if keywords are found
  • Viewed words - Monitors viewed words across the OS and sends captures to Backdrop if keywords are found


1.1. System Requirements


The minimum system requirements for the client are:

  • macOS 10.14 or Higher (macOS Mojave)
  • Google Chrome or Microsoft Edge (v77+ chromium)


1.2. macOS 10.14 supported devices

  • Late 2012 iMac or newer
  • Early 2015 MacBook or newer
  • Mid-2012 MacBook Pro or newer
  • Mid-2012 MacBook Air or newer
  • Late-2012 Mac Mini or newer
  • Late 2013 Mac Pro or newer (2010 or newer with Metal-ready GPU)
  • iMac Pro all models

1.3. Browser Extensions


Browser Extensions are required to perform the following actions and need to be installed to provide the full set of Classroom functionality.

  • Block Internet Access.
  • Allow/Block Website Lists.
  • View/Close browser tabs.

For more details on browser extensions, click on the following link:

To download the Chrome Extension, click on the following link:


1.4. Download Backdrop macOS Client


To download the macOS Client, click on the following link:


1.5. Release Notes - v1.1.0 - 3rd September 2021


Major changes

  • Added Wellbeing support (Viewed/Written word captures)


Bug fixes

  • none


Features

  • Written words - Monitors typed words and sends captures to Backdrop if keywords are found
  • Viewed words - Monitors viewed words across the OS and sends captures to Backdrop if keywords are found
  • Send device session ID in telemetry
  • Add option to hit keyboard return key to trigger Login
  • Add Branding to Lock Screen Message
  • Improve logging



The macOS client changelog can be found at the following link: Impero Classroom - macOS Client Change Log/Release Notes



2. Installation


The following installation guides describe the process of installing the Backdrop macOS client.


2.1. Single Device Installation via Installer

1. Download the DMG file and run. Double click the Impero.pkg to begin the installation process.

2. The "Welcome to the Impero Installer" setup wizard is displayed.

3. Click on "Continue".

4. The Installer displays which disk it will install to and how much disk space it will use. Click on "Install" to begin the installation process.

5. The installer now prompts for the username and password of the local administrator account. Enter these credentials and click on "Install Software".

6. Once the installation has been completed you are prompted to accept the "System Events" permission. This allows Backdrop to remotely log out the user from the device. Click on "OK" to this message.

7. Now that installation has been completed, click on "Close" on the Installer wizard.

8. The school code registration form automatically appears once the macOS client has started running.

9. Enter the school code the device is provisioning against and click on "Next".

10. The user login screen appears next. You see the name of the school you have provisioned against displayed. Enter the credentials to log a student in, found under "Access Details" on the student profile or "Login Details" under Administration.
If you are using automatic login identifiers then step 10 is skipped.


2.2. Mass Deployment Requirements


Mass deployment is the process of installing the Backdrop macOS client to many devices in a single action and providing school code and login details so that the client can connect to correct school and student without user interaction. The following lists the requirements needed to perform mass deployment of the macOS client.

Setting Up Meraki MDM:

 

Step 1 Add A Device:

 

Graphical user interface, application

Description automatically generated

 

Graphical user interface, application

Description automatically generated

 

Graphical user interface, text, application, email

Description automatically generated

 

 

 

 

 

Graphical user interface, text, application

Description automatically generated

 

Add Custom App:

 

Installing Applications on Devices

Using Systems Manager, suites of applications can very easily be deployed to end user devices.

 

The following instructions outline how to deploy a new application, as well as overview additional installation options:

 

Navigate to Systems Manager > Manage > Apps

 

Graphical user interface, application

Description automatically generated

Click on the “Add new” dropdown and select either Windows or macOS Custom app:

add-new.png

 

Graphical user interface, text, application, email

Description automatically generated

 

Once an OS Custom app is selected, fill in the following information about the application:

 

Application name: The name of the application as it is displayed on the end device (e.g. Firefox, FileZilla, etc). If the application is already installed on managed clients, it is listed in the drop-down menu. This name can be changed at any time.

 

Graphical user interface, text, application, email

Description automatically generated

 

 

Vendor: The vendor of the specified application.

Version: The version number of the application to be installed.

Description: A brief description of the application.

Install file host: This option denotes whether the application's installer will be hosted in Dashboard, or on an external server (e.g. Dropbox).

Upload to the Meraki Cloud: Select this option and click Browse to upload the installer file directly to Dashboard.

Specify a URL: Select this option if the installer file is hosted on an external server or file share site, and specify the URL for the hosted file. The URL field must point to the direct download link to a publicly hosted file such as the following, or an internally hosted server accessible by the end user's device.

https://www.dropbox.com/s/a1b2c3d4ef5gh6/example.docx?dl=1 (see here)

https://drive.google.com/uc?export=download&id=FILE_ID (see here)

Note: The installer must be silent (require no user interaction) for the application to install correctly in the background. Windows applications can be installed in the foreground in order to prompt user interaction.

 

NOTE: The following installer file types are supported:

-Windows: .exe or .msi 

-macOS: .dmg, .pkg*, or .app*.

 

*A .pkg or .app file can be used, but it must be wrapped in a .dmg. Please refer to Apple's documentation for their recommended steps.

Scope: Specifies a scope of devices that will have this application installed. Please refer to our documentation for more information on scoping by device tag.

Disable install on save: By default, the application will be auto-installed the moment the Save button is clicked. If auto-install is disabled, the application won't be installed until it's manually pushed by navigating to Systems manager > Manage > Apps and selecting Push > Push to all. Dashboard users can manually queue install requests via the device page, or by pressing the Repush buttons on this page.

Install in foreground (Windows-only): Allow the installer to show user prompts, instead of silently installing in the background.

Installation arguments (optional): If the installer must be run with specific command line arguments, they can be listed here.

 

The following list shows the actual install command run on the end-device, where [arguments] refers to the contents of the Installation arguments field in Dashboard:

EXE: application_installer.exe [arguments]

MSI: msiexec /quiet /i application_installer.msi [arguments]

PKG: /usr/sbin/installer [arguments] -pkg application_installer.pkg -target /

Command line (optional): Specifies a command to run after installation has completed. This is commonly used to reboot the machine after installation, using the following commands:

Windows: shutdown /r

OS X: shutdown -r now

 

Click on "Save Changes". Unless auto-install is disabled, this pushes out the application to all devices within the specified scope.

 

Graphical user interface, text, application, email

Description automatically generated

 

 

 

 

 

Monitoring Installation

The status of an installation can be checked via the Monitor > Devices page, by clicking on a particular client and navigating to the Event log or Activity log section.

A picture containing background pattern

Description automatically generated

 

Check that the deployment was a success by logging onto the device and checking under applications:

 

 

Double click the application and you should be presented with the below screen:

 

Graphical user interface, website

Description automatically generated

 

 

 

 

For automatic school enrolment, (so the above screen does not appear for the student), you will need to deploy a plist file in the following location: 

/Library/Application Support/Impero

(Not the USER library but in the SYSTEM library.) 

Here is an example of the plist contents: 

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<plist version="1.0">

<dict>

    <key>schoolcode</key>

    <string>abc123</string>

</dict>

</plist>

 



2.3. Permissions


Firewall
 
If the Mac's firewall is on you might need to add the Impero application in as an exception:
- Open System Preferences.
- Click on the Security or Security & Privacy icon.
- Select the Firewall tab.
- Click on the lock icon in the preference pane, then enter an administrator name and password.
- Click on the Firewall Options button.
- Click on the Add Application (+) button.
- Use the Finder to select the Impero application in the Applications folder.

Permissions
 
The following permissions will need to be set for the Impero application to run properly
- Learners Relay.app: Screen Recording
- Impero.app: Full disk access

Default Browser
Google Chrome must be set as the default browser for Impero application to run properly.



2.3.1 - Screen Recording


The first time a macOS device is viewed in Classroom the Screen Recording permission will be triggered. This permission is required to share the screen of the device. It is a one-time permission that is accepted at the user level meaning each user on the device will get asked the permission individually. The client needs to quit and restart in order to use the permission.


1. Open System Preferences when the Screen Recording permission dialog appears.

2. You may be asked to enter your administrator username and password to change system preferences.

3. The "ImperoRelay" needs to quit and reopen in order to use the permission. Clicking on the "Quit & Reopen" button restarts the client.

4. Once approved the "Learners Relay" appears under the Privacy tab of system preferences.



3. Uninstallation


The following uninstallation guide describes the process of removing the Backdrop macOS client.


1. Download the Impero Backdrop Uninstaller tool here.

2. Extract the zip file and run the Impero Backdrop Uninstaller app.

3. The uninstaller now prompts you for the password of the local administrator account.

4. Delete any items labeled Impero from the Keychain Access app. (Optional)


4. Debug Logs

Debug logs can be accessed from the Mac console app. 


To open the Mac console app press command + space to bring up the spotlight and search for the console.

Click on "Start" to start capturing logs

once started click on Errors and Faults to see if there are any Backdrop faults or search for "Impero" to filter the console view.



To export,  highlight the logs and use the share function to exports to a note or to mail it.

5. FAQ and Troubleshooting


I am not being prompted to login, is the application working?


If you are using automatic log in you are not prompted to log in to Backdrop. Verify the website to see if you appear in the classroom.

If you are not using automatic log in and you are not prompted to appear. Verify that the Impero Daemon and Learners Relay processes are running in Activity Monitor.

Finally, verify your Internet connection. The software requires an Internet connection to work properly. If you have recently fixed a problem with your Internet connection, it is necessary that you restart your macOS device.

If you are still having problems, double-check that the user has the correct application permissions set as described in the installation steps.


I have checked the logs, the client is struggling to connect to IoTHub / Backdrop?


Double-check that the system has the correct Network Access.

Check that your 3rd party firewalls, MDM solutions, or Webcheck is not blocking the solution.


I can not see the live feed in Backdrop or broadcasting a student's screen does not work?


On the student's macOS device:

Verify that your 3rd party firewalls, MDM solutions or Webcheck is not blocking the Impero application.

If the macOS device's firewall is on, you might need to add the Learner's Relay application in as an exception:

Open System Preferences.

Click on the Security or Security & Privacy icon.

Select the Firewall tab.

Click on the lock icon in the preference pane, then enter an administrator name and password.

Click on the Firewall Options button.

Click on the Add Application (+) button.

Use the Finder to select the Impero application in the Applications folder.


Using Keychain Access To Delete Certificate And Keys [keychain]

There are three items in the user's keychain that are used when communicating with Impero's servers, and if any of these are missing or corrupt the client application will be unable to communicate with the server.

If you are seeing issues with initial server connection it may be a good idea to delete these items, so that the client can recreate them and try again.

(Do be careful to only delete these items as a last resort, and only these items; if the wrong things are deleted in the user's keychain it may have unintended consequences with other applications or macOS itself.)


To open Keychain Access (a built-in macOS app) go to `/Applications/Utilities/Keychain Access`, or press Command (⌘) + Space to open Spotlight and search for Keychain Access.

Make sure login keychain is selected on the left-hand side, then click on _Keys_ towards the top of the window to filter the list.

There are two entries in the list named `ImperoCertificateKeys`; go ahead and delete both of those. (There will be a warning, so ensure the correct items are being deleted, and the user has read the warning carefully.)


 
Next, click on _My Certificates_ towards the top of the window to re-filter the list.

Click on each item in turn: if the _Name_ is in the format `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`, and the _Issued by_ entry is `Impero Software Devices Intermediate CA`, you should be OK to go ahead and delete it. (Again, there will be a warning, so be do check carefully.)

Once these are deleted, restart the machine and the Impero client should recreate them as needed.