Internet Filtering (Lightspeed Systems): SSL filtering ... · Apple Mac Configuration (Scripted) Version 1.1 July 2017 Page 4 of 13 Executive summary The purpose of this document

In confidence

Internet Filtering (Lightspeed Systems): SSL filtering Apple Mac Configuration (Scripted)

Reference: BTLS_LS_OSX_Scripts

Version: 1.1

Date: 31 July 2017

Owner(s): Darren Turrell/

Colin Helliwell

BT Lancashire Services Education Services SSL Filtering

Apple Mac Configuration (Scripted)

Version 1.1 July 2017

Page 2 of 13

Contents Page

1 Prerequisites 5

1.1 CLEO connection 5

1.2 Operating systems 5

1.3 BTLS SSL filtering option 5

1.4 Mozilla Firefox 5

1.5 Intended Audience 5

1.6 Administrative Rights 5

2 Running the scripts 6

2.1 How do I make this work? 6

2.2 Script Explanations 6

2.3 Manually executing the configuration scripts 8

2.4 Deploying the scripts through Apple Remote Desktop (ARD) 9

2.5 Firefox scripts 10

2.6 Script testing 11

3 Testing 13




Page 3 of 13

Audience: These notes are intended to be used by your ICT technician, network manager or third party ICT support organisation




Page 4 of 13

Executive summary

The purpose of this document is to assist schools in enabling SSL filtering.

This document details a tool designed to assist schools in the deployment of changes required to school

Apple Mac based computers that are not managed by an MDM tool. Following the running of this tool,

schools will be able to use their Lightspeed admin console reports (at http://filter.education.btlsl.co.uk)

to view the contents of secure searches run on their computers. Additionally Google and Bing search

results will reflect your schools filtering policy.

These notes cover the steps needed to prepare your Apple Mac computers for the Lightspeed SSL

filtering facility.

This must not be run in a school which is not connected to the CLEO network.

This document is for Apple Mac computers only. Please see the other SSL documentation on the BTLS

website for enabling SSL filtering on different devices.

http://filter.education.btlsl.co.uk/




Page 5 of 13

1 Prerequisites

1.1 CLEO connection

This guide should only be followed for machines connected to the CLEO network. If your school obtains

its internet access from another provider, these notes do not apply to you.

1.2 Operating systems

These notes are designed to be used with the following operating systems;

OSX Mountain Lion (10.8), El Capitan (10.11), and Sierra (10.12)

1.3 BTLS SSL filtering option

These notes relate to the secure search filtering option. This enables searches to common search

engines (Google/Bing/YouTube) to be decrypted when a secure search is conducted (a secure search

will begin with https:// rather than http://). As these searches can be decrypted, schools can use the

Lightspeed reporting functions to see what their students and staff have been searching for, and have

school policies applied. This patch can be run either before or after having this service enabled for the

school, but it cannot be tested successfully until the service has been enabled.

All other search engines will be disabled as part of this change.

1.4 Mozilla Firefox

Firefox uses its own certificate store and proxy auto configuration (PAC) settings, though the default

for proxy settings is to use the system proxy settings. A separate script for Firefox is available in our

Apple Mac Script pack, this utilises an auto-config method, created by using the CCK2 plugin

(https://mike.kaply.com). If schools wish to amend these settings, please follow the link for

associated documentation. BTLS cannot offer support on the CCK2 plugin.

1.5 Intended Audience

This change should be undertaken by your local ICT Technician, Network Manager or Third party ICT

support team.

1.6 Administrative Rights

You must have administrator rights over the individual apple mac computers. Without administrative

rights these reconfiguration steps will not function correctly.

https://mike.kaply.com/




Page 6 of 13

2 Running the scripts

Please be aware the following instructions require reconfiguration steps to your Apple Mac computers and misconfiguration may cause them to experience issues or fail. These steps should only be conducted by someone with the appropriate skills. Please also ensure that you fully test the deployment before rolling it out to all your workstations, and you have a method in place to restore the computer back to its original state if it does not work as desired i.e. a time machine backup, or details of how to reset the network settings of the machines you are working on.

2.1 How do I make this work?

We have produced a set of scripts which can be run either directly on your computers or pushed out

through a tool such as Apple Remote Desktop. These scripts should only be imported for use with

operating systems listed in section 1.2 of this guide other untested versions of mac OS X are run at

your own risk. We recommend that you pass these guidelines to your network manager, ICT

technician or third party support organisation to complete.

We need to consider two types of devices, mobile (MacBook's etc. and fixed (iMacs etc.), the mobile

devices only need to be considered as mobile if they are traveling between School and external

locations (i.e. home). These devices will either need to use Ethernet in School and Wi-Fi externally or

vice versa, or be configured to have multiple network locations.

Further information about network locations including how to switch location can get found on Apples website; https://support.apple.com/en-gb/HT202480 Once you have determined if you have devices that move location and decided on a method to deal

with this, you can proceed.

2.2 Script Explanations

There are several scripts which I will explain below, these scripts can be edited to suit your particular environment but caution should be taken in doing so. The scripts provided have been run on test computers before being deployed to working systems but the School is advised to carry out their own tests before using either the original script or a modified version as we cannot test every possible setup. You would be advised to use a script editor rather than using the in-built TextEdit as this is not very well suited to creating scripts, in particular TextEdit will auto correct " with “ if you edit any of the enclosed characters which will cause the script to fail. A script editor can also help identify syntax errors by highlighting them, I have used TextMate but there are plenty of other editors that may be better suited to your needs. The latest certificate should also be obtained from the following URL and placed in the same folder as the script being executed if run locally. You should place the certificate in the root folder of the computer if executing via Apple Remote Desktop.

https://support.apple.com/en-gb/HT202480




Page 7 of 13

http://filter.education.btlsl.co.uk/lsaccess/proxycerthelp Script name and version number Description

AutoLocationWiFi+EthernetVx.y.sh Installs the certificate and configures the proxy settings for the Automatic locations (the default one created) for the Wireless and Ethernet connections, it will also clear any other proxy settings already in place on the Automatic location

Home+SchoolEthernetOnlyVx.y.sh Installs the certificate and creates two new network locations (Home + School), then configures the proxy settings for the School location on Ethernet only, it will also delete the default Automatic location

Home+SchoolWiFi+EthernetVx.y.sh Installs the certificate and creates two new network locations (Home + School), then configures the proxy settings for the School location on Wireless and Ethernet, it will also delete the default Automatic location

Home+SchoolWiFiOnlyVx.y.sh Installs the certificate and creates two new network locations (Home + School), then configures the proxy settings for the School location on Wireless only, it will also delete the default Automatic location

CertificateInstallOnlyVx.y.sh Installs the certificate and leaves all proxy settings alone

ResetToAutomaticLocationVx.y.sh Deletes the Home and School locations and recreates the Automatic location – all settings lost (this script is for testing purposes)

FirefoxInstallCertificate+ProxyURL.sh Installs the certificate in Firefox's certificate store and sets the Auto proxy URL in Firefox's advanced preferences page

FirefoxARDInstallCertificate+ProxyURL.sh Same as above but designed for use with Apple Remote Desktop only – will not work as a standalone

http://filter.education.btlsl.co.uk/lsaccess/proxycerthelp




Page 8 of 13

2.3 Manually executing the configuration scripts

It is possible to run the scripts across multiple clients at the same time using tools such as Apple Remote Desktop, rather than having to visit each machine manually. We will first show how to run manually at each machine then explain how to deploy using Apple Remote Desktop later.

Instructions Screenshot

Start Terminal and execute the script by dragging the script in to the terminal window and pressing enter.

You will be prompted for Admin user credentials

Your chosen script will execute outputting the actions and success/failure at each stage. If the script fails at any stage it will stop and state the error, you will need to investigate the cause of the error but most likely the logic of the script did not match how your machine was configured.




Page 9 of 13

2.4 Deploying the scripts through Apple Remote Desktop (ARD)

There are several was to deploy the settings even just using Apple Remote Desktop, for simplicity sake I we describe only one method you are free to adapt this if you have another solution but we will only be able to provide support on the described method.

Start Apple Remote Desktop (ARD) and go to "All Computer" then select the computers you want to deploy to (remember to thoroughly test before deploying to your users environment) Click on "Copy"

Add the certificate that can be downloaded from: https://filter.education.btlsl.co.uk/lsaccess/proxycerthelp

For simplicity sake we will just copy the certificate to the root of the computer's hard drive by selecting "Top folder of the disk" under "Place items in" Click "Copy" when you are happy with the other options

You will receive a copy success message like this one if everything went correctly

Sending a UNIX Command by selecting the computers you wish to deploy to and click "UNIX", this will bring up the "Send UNIX Command" dialogue box Change the user to "root" Copy and paste the script contents in to the top box

Go to "Template" then "Save as Template" Name the template the same as the script and press return.

https://filter.education.btlsl.co.uk/lsaccess/proxycerthelp




Page 10 of 13

You should receive a UNIX command send success message like the one opposite

You will also get a detailed output box for the command that will have an entry for each computer you have deployed to The script will output success or failure messages for each of the commands it tries to run and for each machine Any failures should be investigated

2.5 Firefox scripts

Two scripts are available to install the certificate and proxy settings required, a standalone script and an Apple Remote Desktop version. The standalone script can be run by following the notes for "2.3Manually executing the configuration scripts" above. The ARD version of the script can be used by following the notes below, but requires a shared folder and a valid user account with permissions to the shared folder. You will be required to edit the script to include this users credentials and so it should not be your main admin account as the account details we be stored within ARD in plain text. A new sharing account should be set up for the script to use, that will only have permissions to the scripts folder on a network share;

Go to "System Preferences" then "Users & Groups" and unlock to make changes Create a new user account and set to "Sharing only" This account will be used by the script to copy files out of the shared folder If you don’t already have a shared folder on your ARD computer create a new folder at the root of your drive and share it, the SSL Account only needs read access to this one folder but you must edit the script to include the SSL Account credentials and the script folder path Share the folder by going to "System Preferences" and adding a shared folder The SSL Account should be given "Read Only" permissions




Page 11 of 13

You will see the computers name in the smb share path under "File Sharing: On"

Unpack the full folder FirefoxAutoConfig in to your shared folder from the scripts zip file, the script will look inside this folder for the CCK2 folders and files

The script "FirefoxARDInstallCertificate+ProxyURL.sh" needs to be edited to include the sharing account you created and the servername/shared folder path you previously set up Please read the advice on 2.2 regarding using a script editor to modify these scripts If you have problems mounting the shared folder after editing the script, try replacing the servername with the servers ip address instead

Follow the rest of the instructions from 2.4 starting at "Sending a UNIX Command" (the third box down

2.6 Script testing

You should test the script has executed as expected on the first 5% - 10% of each deployment type manually to ensure it is working as expected. If problems are found these should be corrected and more computers should be tested. You are testing that the proxy settings have been applied correctly for the network location you want to use and that the certificate has been installed in to the system keychain access store correctly.

Open network preferences and switch to the location you want to check.




Page 12 of 13

Click on "Advanced"

Click on "Proxies" and then "Automatic Proxy Configuration" and check the URL has been updated correctly by the script Cancel back out of all Preferences when finished and ready to check the certificate has been installed

Open "Keychain Access" from utilities through the "Finder" menu at the top of your screen under "Go" or searching via spotlight (top right).

Select "System" and look for "Lightspeed Rocket" Double click this certificate and click the disclosure triangle to check the trust levels, "Secure Sockets Layer (SSL) should be marked as "Always Trust"




Page 13 of 13

3 Testing

After reconfiguration, schools should test devices to ensure that the SSL filtering is working correctly.

Please follow the steps below:

Instructions Screenshot On the device to be tested, open a

web browser and navigate to

https://images.google.com/ .

Enter the word "pokerchip".

Correct configuration

If filtering is running correctly,

some of the returned thumbnails

will have a blue cross image.

These blue crosses represent

results from blocked websites.

Incorrect configuration

If filtering is not running correctly,

all images will be returned.

Please check the configuration on

this device.

https://images.google.com/

Documents

Internet Filtering (Lightspeed Systems): SSL filtering ... · Apple Mac Configuration (Scripted) Version 1.1 July 2017 Page 4 of 13 Executive summary The purpose of this document