Managing Mac Kiosks

#!/bin/sh

# Check to make sure the library and command-line API are both installed
if [[ -e /Library/Python/2.7/site-packages/display_manager_lib.py && \
-e /usr/local/bin/display_manager.py ]] ; then

    # Positional parameters. If not mentioned, will stay empty
    res=""
    rotate=""
    brightness=""
    underscan=""
    mirror=""

# Set positional parameters if mentioned
if [[ -n  "$4" ]] ; then
    res="res $4"
fi
if [[ -n  "$5" ]] ; then
    rotate="rotate $5"
fi
if [[ -n  "$6" ]] ; then
    brightness="brightness $6"
fi
if [[ -n  "$7" ]] ; then
    underscan="underscan $7"
fi
if [[ -n  "$8" ]] ; then
    mirror="mirror $8"
fi

/usr/local/bin/display_manager.py $res $rotate $brightness $underscan $mirror

else
    exit 1
fi

And run it ongoing at every login and via custom trigger to allow easy ad-hoc execution to set display settings.

sudo jamf policy -event DigitalDisplay -verbose

If your environment isn’t using Jamf Pro, you could easily use a similar methodology with tools like Outset or custom launch item to run based on your environment needs.

We decided to use Google Chrome for our browser kiosk implementation using Chromimum command line switches.

Using the this command format:

/path/to/Google Chrome.app/Contents/Google Chrome [SWITCH]

We used the following switches:

• –kiosk
  Enable kiosk mode with Google Chrome in full screen.
  
  /path/to/Google Chrome.app/Contents/Google Chrome –kiosk
  
  
  

• • –app=[WEB ADDRESS]
    Specifies that Google Chrome should be launched in “application” mode without address bar.
    
    /path/to/Google Chrome.app/Contents/Google Chrome –kiosk –app=https://lib.utah.edu
    
    

• –force-first-run
  Displays the First Run experience when the browser is started, regardless of whether or not it’s actually the First Run (this overrides kNoFirstRun).

Process Overview
Here is an overview of how the various pieces of our kiosk system work together:

Script
Here is the python script we are using with our kiosk implementation. It launches Google Chrome based on command line switched based via configuration property list, then uses AppleScript to verify its the frontmost application, verifies if screen saver is running using pgrep, uses ioreg to verify is display is asleep,  removes Google Chrome profile to cleanup previous user session,  and based on conditions will restart Google Chrome if necessary like if it has crashed, quit by user or if screen saver activated or display asleep, etc.

#!/usr/bin/python
# -*- coding: utf-8 -*-

from __future__ import print_function

import sys
import os
import subprocess
import time
import re
import plistlib
import signal
import shutil
import logging
import json
from datetime import datetime, timedelta

from management_tools import loggers

'''Keep Google Chrome Running in Kiosk Mode
'''

__author__ = "Sam Forester"
__email__ = "sam.forester@utah.edu"
__copyright__ = "Copyright (c) 2018 University of Utah, Marriott Library"
__license__ = "MIT"
__version__ = '1.9.1'
__url__ = None
__description__ = 'Keep Google Chrome Running in Kiosk Mode'

## CHANGELOG:
#   1.8.0: (2018.10.18)
#       - added remove_user_chrome_profile
#       - modified switch processing
#       - added more logging
#       - added logging stream handler and --verbose flag
#       - modified run loop
#       - replaced set_restart to restart_timer
#       - modified restart_timer to allow for null timers
#       - added pgrep
#       - modified screensaver_is_running to use pgrep()
#   1.8.1: (2018.10.18)
#       - fixed bug that would cause endless tabs to be re-opened
#         if Google Chrome was running at RunTime
#       - renamed launch_chrome_with_switches to launch_chrome
#       - fixed bug causing looping to move too fast during screensaver
#   1.8.2: (2018.10.18)
#       - fixed bug that was not allowing user profile to be removed
#       - added faster loop to restore Chrome after screensaver
#   1.9.0: (2018.10.19)
#       - added better mechanism for checking frontmost window
#       - added ability to detect display sleep
#   1.9.1: (2018.10.19)
#       - fixed error with Popen.call()
#       - fixed parameter error

class SignalTrap(object):
    '''Class for trapping interruptions in an attempt to shutdown
    more gracefully
    '''
    def __init__(self, logger):
        self.stopped = False
        self.log = logger
        signal.signal(signal.SIGINT, self.trap)
        signal.signal(signal.SIGQUIT, self.trap)
        signal.signal(signal.SIGTERM, self.trap)
        signal.signal(signal.SIGTSTP, self.trap)

    def trap(self, signum, frame):
        self.log.debug("received signal: {0}".format(signum))
        self.stopped = True


def app_is_frontmost(name):
    '''Uses applescript to see if specified app name running and
    frontmost window.

    Returns True or False
    '''
    # doesn't require Accessibility access
    scpt = ['tell application "System Events"',
                'try',
                    'tell process "{0}"',
                        'if (frontmost is false) then return false',
                    'end tell',
                    'tell application "{0}"',
                        'return (count of windows) is greater than 0',
                    'end tell',
                'on error',
                    'return false',
                'end try',
            'end tell']
    # join all the strings and then format
    applscpt = "\n".join(scpt).format(name)
    cmd = ['osascript', '-e', applscpt]
    try:
        out = subprocess.check_output(cmd).rstrip()
        return True if out == 'true' else False
    except subprocess.CalledProcessError:
        return False

def screensaver_is_running():
    '''Returns True if ScreenSaverEngine is running
    '''
    return pgrep(None, 'ScreenSaverEngine')

def restart_timer(logger=None, **kwargs):
    '''Returns a closure that uses the time of assignment 
    to return True if that amount of time has passed
    if given 

    ::params:: anything that can be used by datetime.timedelta()

    >>> restart = set_restart(seconds=5)
    >>> time.sleep(1)
    >>> restart()
    False
    >>> time.sleep(5)
    >>> restart()
    True
    >>> restart()
    True

    >>> restart = set_restart(hours=2)
    >>> time.sleep(1)
    >>> restart()
    False
    >>> time.sleep(7,200)
    >>> restart()
    True

    >>> restart = set_restart(seconds=0)
    >>> time.sleep(1000)
    >>> restart()
    False
    >>> time.sleep(5)
    >>> restart()
    False

    '''
    now = datetime.now().replace(microsecond=0)
    restart = now + timedelta(**kwargs)
    empty = (now == restart) or (restart < now)
    if logger and not empty:
        logger.debug("restart timer set: {0}".format(restart))
    def _restart():
        if empty:
            return False
        else:
            return datetime.now() > restart
    return _restart

def display_power():
    '''Uses `ioreg` to return values of IODisplayWrangler's 
    IOPowerManagent
    '''
    cmd = ['/usr/sbin/ioreg', '-w', '0', '-n', 'IODisplayWrangler', 
                                         '-r', 'IODisplayWrangler']
    out = subprocess.check_output(cmd)
    m = re.search(r'"IOPowerManagement" = (\{.+\})', out, re.MULTILINE)
    # convert ioreg out put into something more JSON-y
    j = m.group(1).replace('=', ':')
    return json.loads(j)

def display_sleep():
    '''Returns True if display is asleep
    '''
    if display_power()["CurrentPowerState"] < 3:
        return True
    else:
        return False

def pgrep(logger, name):
    '''Uses /usr/bin/pgrep to return list of running PIDs.
    returns empty list if no PIDs are found
    '''
    if not logger:
        logger = logging.getLogger(__name__)
        logger.addHandler(logging.NullHandler())
    cmd = ['/usr/bin/pgrep', name]
    logger.debug("> {0}".format(" ".join(cmd)))
    p = subprocess.Popen(cmd, stdout=subprocess.PIPE,
                              stderr=subprocess.PIPE)
    out, err = p.communicate()
    if p.returncode == 0:
        pids = [x for x in out.splitlines() if x]
        logger.debug("{0}: pids: {1}".format(name, pids))
        return pids
    else:
        return []
    
def remove_user_chrome_profile(logger):
    '''Removes ~/Library/Application Support/Google
    '''
    user_d = os.path.expanduser('~/Library/Application Support/Google')
    logger.debug("removing user chrome settings: {0}".format(user_d))
    try:
        shutil.rmtree(user_d)
    except OSError as e:
        # skip OSError: [Errno 2] No such file or directory
        logger.error("unable to remove: {0}: {1}".format(user_d, e))
        if e.errno != 2:
            #logger.error("unable to remove: {0}".format(user_d))
            raise
    if os.path.exists(user_d):
        logger.debug("still exists: {0}".format(user_d))

def launch_chrome(logger, switches, app=None, reset=True):
    '''Launches Google Chrome in with specified flags
    '''
    if not app:
        # default Google Chrome.app location
        app = '/Applications/Google Chrome.app'

    if reset:
        remove_user_chrome_profile(logger)

    chromebin = os.path.join(app, 'Contents/MacOS/Google Chrome')
    cmd = [chromebin] + switches
    logger.debug("> {0}".format(" ".join(cmd)))
    p = subprocess.Popen(cmd, stdout=subprocess.PIPE, 
                              stderr=subprocess.PIPE)
    logger.debug("chrome PID: {0}".format(p.pid))
    return p

def main(args):
    '''Launch Google Chrome and make sure it's in the foreground
    '''
    script = os.path.basename(sys.argv[0])
    scriptname = os.path.splitext(script)[0]

    level = loggers.INFO
    if '--debug' in args:
        level = loggers.DEBUG

    logger = loggers.FileLogger(name=scriptname, level=level)
    if '--verbose' in args:
        sh = loggers.StreamLogger(level=level)
        logger.addHandler(sh)

    logger.debug("{0} started!".format(script))
    settings = '/Library/Management/edu.utah.mlib.kiosk.settings.plist'
        
    # get settings from file
    try:
        logger.debug("getting settings from: {0}".format(settings))
        config = plistlib.readPlist(settings)
    except Exception as e:
        logger.error(e)
        raise

    try:
        site = config['site']
    except KeyError:    
        logger.error("no site was specified")
        raise SystemExit("no site was specified")

    # add any additionally specified switches
    switches = config.get('switches', [])
    
    switches += ['--kiosk']
    if config.get('isDisplay'):
        switches.append("--app={0}".format(site))
    else:
        switches.append(site)

    # path to chrome app (default: /Applications/Google Chrome.app)
    app = config.get('location', '/Applications/Google Chrome.app')
    logger.debug("location: {0}".format(app))
    
    # seconds to wait between loops
    wait = config.get('wait', 5)    
    logger.debug("wait: {0}".format(wait))

    # timer to restart: (default: def _(): return False)
    restart = config.get('restart', -1)
    logger.debug("restart seconds: {0}".format(restart))
    time_to_restart = restart_timer(seconds=restart)

    # clear user profile between launches (default: True)
    reset = config.get('remove-profile', True)    
    logger.debug("remove profile: {0}".format(reset))

    # Kill any running instances of Google Chrome (or endless tabs)
    pids = pgrep(logger, "Google Chrome")
    if pids:
        logger.debug("Chrome was already running... killing...")
        cmd = ['/usr/bin/killall', "Google Chrome"]
        logger.debug("> {0}".format(" ".join(cmd)))
        subprocess.Popen(cmd, stdout=subprocess.PIPE,
                              stderr=subprocess.PIPE).wait()
    # start Google Chrome
    logger.info("starting Google Chrome")
    chrome = launch_chrome(logger, switches, app, reset)

    sig = SignalTrap(logger)
    while not sig.stopped:
        # if chrome.poll() returns anything but None, it exited
        running = chrome.poll() is None

        if screensaver_is_running() or display_sleep():
            if running:
                logger.debug("closing chrome while display inactive")
                chrome.terminate()
                chrome.wait()
            # TO-DO: would like to keep this from looping every second
            # during screensaver, but that's for another day
            time.sleep(1)
            continue

        # Automatically restart Chrome after a certain amount of time
        if time_to_restart():
            msg = "restarting after {0} seconds".format(restart)
            logger.debug(msg)
            logger.debug("resetting restart timer")
            time_to_restart = set_restart(seconds=restart)
            if running:
                chrome.terminate()
                chrome.wait()
                continue
            else:
                logger.debug("chrome wasn't running... odd")
            logger.debug("resetting restart timer")
            time_to_restart = set_restart(seconds=restart)
        
        # check to see that Chrome is the frontmost process
        if running and not sig.stopped:
            if not app_is_frontmost("Google Chrome"):
                logger.debug("Google Chrome isn't active")
                chrome.terminate()
                chrome.wait()
                running = False

        # Finally, restart chrome if it isn't running
        if not running:
            logger.error("chrome isn't running")
            pid = chrome.pid
            poll = chrome.poll()
            logger.debug("dead chrome: {0} poll: {1}".format(pid,poll))
            # relaunch chrome
            chrome = launch_chrome(logger, switches, app, reset)
        time.sleep(wait)

    chrome.terminate()
    logger.debug("{0} finished!".format(script))
    return 0

if __name__ == '__main__':
    try:
        args = sys.argv[1:]
    except IndexError:
        args = []
    retcode = main(args)
    sys.exit(retcode)

With the following LaunchAgent:

<?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>POSIXSpawnType</key>
	<string>App</string>
	<key>LimitLoadToSessionType</key>
	<string>Aqua</string>
	<key>KeepAlive</key>
	<dict>
		<key>SuccessfulExit</key>
		<false/>
	</dict>
	<key>Label</key>
	<string>edu.utah.mlib.kiosk.chrome.display</string>
	<key>CFBundleIdentifier</key>
	<string>com.google.Chrome</string>
	<key>Program</key>
	<string>/usr/local/bin/chrome_kiosk.py</string>
	<key>StandardOutPath</key>
	<string>/tmp/chrome_kiosk.log</string>
	<key>StandardErrorPath</key>
	<string>/tmp/chrome_kiosk.log</string>
</dict>
</plist>

This LaunchAgent sends standard output to /tmp/chrome_kiosk.log , standard error to /tmp/chrome_kiosk.log , will keep alive if the script fails and is limited to Aqua session.

Apple Technical Note named “Daemons and Agents” that explains most of the session types available for launchd.

• Aqua – GUI agent which has access to all the GUI services
• LoginWindow –  Pre-login agent which runs in the login window context
• Background –  Runs in the parent context of the user
• StandardIO – Runs only in non-GUI login session (i.e SSH sessions)

A useful GUI application that allows you to create, manage, debug & learning system and user services & options on Mac systems is named, LaunchControl.

The property list that is used to define individual kiosk configurations either can be customized using the defaults command or a configuration profile:

<?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>isDisplay</key>
	<false/>
	<key>site</key>
	<string>https://lib.utah.edu</string>
	<key>location</key>
	<string>/Applications/Web Browsers/Google Chrome.app</string>
	<key>switches</key>
	<array>
    	<string>--force-first-run</string>
	</array>
	<key>wait</key>
	<integer>5</integer>
	<key>restart</key>
	<integer>7200</integer>
	<key>remove-profile</key>
    <true/>
</dict>
</plist>

Which we store on our kiosks at the following location:

/Library/Management/edu.utah.mlib.kiosk.settings.plist

Future

In the future we we might migrate from Privoxy to EZProxy after it has been thoroughly tested and staged. We are currently using EZproxy to provide access from outside our library’s network to restricted-access websites that authenticate users by IP address and if it will give us similar functionality as Privoxy with our kiosk implementation would lessen the amount of proxy services we are supporting.

If there is interest by the community in our kiosk methodology and code, we will clean it up and make it more community friendly and post to our public GitHub repository. Let us know by using our contact us page or post a comment to this blog post.