Boot Runner 2 Admin Guide

Created On
Last Updated On
byTimothy Perfitt
You are here:

Table of Contents

  1. Boot Runner Overview
  2. Installing Boot Runner
  3. Users & Groups Settings
  4. Selection Screen
  5. Configure Selection Screen
  6. Volume Options
  7. Marquee Options
  8. Additional Configuration
  9. Boot Runner Menu Bar
  10. Managing Boot Runner
  11. Configuration Profiles
  12. Install Configuration Profile
  13. Managed Client for OS X
  14. Additional Options

Boot Runner Overview back to top^

Boot Runner 2 supports physical startup volumes as well as virtual machines, making it easy to offer selections of any combination of OS X, Windows, Chrome OS, Linux, and other systems installed natively or in a virtual machine. Boot Runner 2 also includes new customization options to make the startup selection screen easier for end users to find and start the OS environment that they need.

Startup control with Boot Runner can be fully integrated with existing client management consoles using Profiles or Managed Client for OS X policy. This Admin Guide includes details on all available keys that can be controlled through profiles.

This  Admin Guide will also cover install, configuration and deployment of Boot Runner.

Installing Boot Runner back to top^

Boot Runner is installed via an OS X installer package, making it easy to install locally or with a client management utilities.

To install Boot Runner:

  1. Double click on the installer icon.
  2. Click Continue and proceed through the install process.
  3. Following successful installation click Close.

The installer places files in three locations:
/Library/PrivilegedHelperTools/Boot Runner.app
/Utilities/Boot Runner Config.app
/Library/LaunchAgents/com.twocanoes.bootrunner.plist

Settings in the Boot Runner Config utility are saved to /Library/Preferences/com.twocanoes.bootrunner.plist

 

Set Users & Groups System Preferences 

The Boot Runner Selection Screen runs on top of the OS X login screen.  In order for Boot Runner to display the Selection Screen containing the available start up disks, Automatic Login must be disabled on the client system.  Go to System Preferences-> Users and Groups-> Login Options-> 

and Set “Automatic Login” to Off

Also, when using virtual machine volumes, the Login window must be set to “Name and password.”  Go to System Preferences-> Users and Groups-> Login Options-> 

and Set “Display Login window” to Name and password 

 

Using Boot Runner: Selection Screen back to top^

The Boot Runner selection screen appears at startup or following logout from OS X. Bootable volumes are presented as selectable disk icons.

The Boot Runner Selection Screen has four main components:

  1. Background: Like the desktop background, scaled to fill the entire screen.
  2. Popover text: Provides additional information above each disk or volume.
  3. Label: Defaults to the disk name, but can be customized in the Boot Runner Config app.
  4. Marquee text: Provides scrolling text across the upper or lower portion of the screen, providing additional information.

Boot Runner Selection Screen Options back to top^

To watch the video please visit: 

Configure Selection Screen Options Boot Runner

To customize the Boot Runner Selection Screen, open up “Boot Runner Config” under Utilities. 

The top third of the preference pane contains settings that affect the look and feel of the Boot Runner Selection Screen:

  1. Custom Background Image Path: Desktop pictures or any standard format image may be used (formats include .jpg, .tif, .png, .pdf). Select an image by using the Select button, entering a path or dragging an image file onto the window.
  2. Hide volumes: Enter the name or device of any bootable volumes that you do not want displayed in the Boot Runner Selection Screen.
  3. Automatically select volume: Use the device name or identifier to select a default boot volume. You can specify the time period when this default will be in effect and Boot Runner will automatically reboot and boot into the specified volume.  Uncheck if you only need to manually reboot into the specified volume.
  4. Show unmounted volumes: Enter the device (for example, disk0s4) of any unmounted volumes that you would like shown on the Boot Runner Selection Screen.
  5. Click Apply to authenticate and save the settings.

Note: If you wish to enter more than one volume in these fields, separate the values with a comma.

 

Boot Runner Volume Options back to top^

To customize the Boot Runner Volume Options, go to Utilities-> Boot Runner Config to view settings.

The Volume Descriptions section is where each volume and associated descriptions are located. Add a volume to the volume descriptions list in order to customize information for the Selection Screen.

  1. Name or Identifier: The volume name or device ID used when mounted in OS X. The volume name is the name shown on the mounted volume in this Finder window and mounted on the desktop. You can find both volume name and device ID by Option-clicking the Boot Runner Menu Item (see below for more details on the Boot Runner Menu Item).
  2. Label: Enter a name that users will see below the volume on the Boot Runner Selection Screen. 
  3. Operating System: Click to select the appropriate operating system or choose “Auto Detect.” Note: Auto detect will not work with unmounted volumes. The selection of operating system will determine the icon that shows up next to each disk and the icon in the popover description.
  4. Popover text: Enter text to describe the volume. This text will be displayed in a popover above the volume on the main selection screen. Note that text may be formatted as needed (6).
  5. Path to RTF File: Enter the path location to a RTF format text document containing descriptive information about the volume. The document must be in Rich Text (RTF) format (TextEdit can create RTF formatted documents) which allows basic text formatting without images.
  6. Formatting Bar for text (available in 10.7 and 10.8 only).

 

 

Boot Runner Marquee Options back to top^

The Marquee displays stationary or scrolling text on the Boot Runner Selection Screen.

1. Marquee text: Enter text that will scroll across the Boot Runner Selection Screen.
2. Marquee text position: Choose the position (top or bottom of the screen) for text.
3. Marquee text scrolling: Select option to enable scrolling marquee text.

 

Configuring Boot Runner: Additional Options back to top^

The bottom of the Boot Runner Config window contains settings for the Boot Runner Selection screen, the Boot Runner Menu Item and display options for restart and shutdown buttons.

  1. If a single Mac volume, bypass Boot Runner: Check this box to bypass running Boot Runner on single volume OS X Macs. For mass deployments where some Macs only host one bootable volume, the Boot Runner Selection Screen will not appear unless additional boot volumes are added. 
  2. Show Boot Runner in menu bar: Check this box to display the Boot Runner menu bar.

 

 

Enabling the Boot Runner Menu Bar back to top^

The Boot Runner Menu Bar provides volume information and a convenient option to select alternate boot volumes directly from the OS X desktop.

To enable the Boot Runner Menu Bar, open Boot Runner Config and select “Show Boot Runner in menu bar.”

 

Using Boot Runner Menu Bar back to top^

Click the Boot Runner menu bar. A menu will drop down containing a list of the volumes on the computer. The active volume will be greyed out.

 

 

Using Boot Runner Menu Bar: Option key select back to top^

Hold down the Option key while clicking the Boot Runner icon to view additional information about the volumes.

 

 

Using Boot Runner Menu Bar back to top^

To select a volume, click on one of the images that is not greyed out. The Boot Camp volume in this illustration is selectable. Once a volume is selected, Boot Runner will prompt “Are you sure you want to select the volume <SELECTED> and reboot?”. Clicking OK will cause the computer to reboot into the selected volume.

 

Managing Boot Runner back to top^

Network administrators can easily manage and configure Boot Runner on multiple Macs using Configuration Profiles or Managed Client for OS X. This section outlines the necessary keys required to manage Boot Runner via configuration profiles or Managed Client for OS X policy.

Managing Boot Runner: Configuration Profiles back to top^

Configuration Profiles were introduced in OS X 10.7 Lion and allow for an easy way to configure settings on OS X.

Boot Runner includes a sample configuration profile with the application and the key values, described below, can be edited in any text editor. Save the configuration profile to a file that ends with the extension .mobileconfig. For example: Bootrunner.mobileconfig.

To install a configuration profile for Boot Runner, simply double click on the configuration profile or use the profiles command to install it. More information on the profiles command can be found in the manual by opening the Terminal application and typing man profiles.

To view the preference file, open Terminal and enter: 

sudo defaults read /Library/Preferences/com.twocanoes.bootrunner.plist

To edit a key in the preference file, use defaults write, for example:

sudo defaults  write /Library/Preferences/com.twocanoes.bootrunner.plist LimitTimeFrom -int 2

to edit multiple keys, export the plist to a text or prefs editor, make changes and re-import.  Do not edit the preference file directly as cached preferences may not sync correctly.

CustomBackgroundPath – (string) location of local image file for selection screen background (TIFF, PNG, JPG or PDF)

HiddenVolumeNames – (string) name or identifier of existing volume that should not appear in selection screen, separate multiple volume names with commas

AutomaticallySelectVolume – (string) name or identifier of existing volume to be selected and booted automatically

AutoSelectTimeout – (integer) delay in seconds between when selection screen appears and when auto selection and booting begins

LimitTimeFrom – (integer) start of period when specified volume should automatically be selected and booted, range from 0-23

LimitTimeTo – (integer) end of period when specified volume should automatically be selected and booted, range from 0-23

LimitTimes – (boolean) yes/no to activate LimitTimeFrom and LimitTimeTo

ShowUnmountedVolumes – (string) name or identifier of volume (usually external drive) that may not always be mounted but will appear in the selection screen.

VolumeDescriptions – (array) key-value clusters for each volume, not editable. Volume property sets assigned by Item number dictionaries (Item 0, Item 1, Item 2, etc)

  • VolumeName – (string) name or identifier, disabled for virtual machine volumes
  • VolumeLabel – (string) displayed under the volume graphic
  • VolumeType – (integer) Operating System icon. 0-auto-detect, 1-OS X, 2-Windows XP, 3-Windows 7, 4-Windows 8, 5-Windows 10, 6-Linux, 7-Other, 8-Custom 
  • VolumeDescriptionRTF – (string) encoded raw text entered into the popover text window. VolumeDescriptionRTF takes precedence over Volume Descriptions if both keys are present.
  • VolumeDescriptions – (string) path to a rich-text format, base64-encoded file containing the popover text (not to be confused with the array of the same name). 
  • VMPath – (string) path, including open command to launch the virtual machine
  • VMUsername – (string) OS X login name to auto-login and launch virtual machine
  • VMPassword – (string) OS X password to auto-login and launch virtual machine
  • UseVM – (boolean) yes/no
  • LogoutFile – (string) name of touched file, defaults to /Users/Shared/.com.twocanoes.bootrunnerlogout
  • VMPostrunScript – (string) path to script file for actions post-vm logout/shutdown. Defaults to /Library/Application Support/Twocanoes/Boot Runner/logoutscript 
  • CustomVolumeGraphic – (string) path to customized image used as icon overlay on volume and in popover, 256 x 256 works best
  • CustomDiskGraphic – (string) path to customized image used instead of default disk icon, 512 x 512 works best

TypingDelay – (integer) in nanoseconds to delay between keystrokes when auto-login VMUsername and VMPassword are enabled.  It should be a number value between 0 and 100,000,000 (100 Million is 1 second). Default is 0. 

MarqueeText – (string) contents of marquee text that appears on the selection screen

MarqueeTextPosition – (integer) integer value that defines where to place the marquee text. Zero (0) shows at top of screen, one (1) shows it at the bottom of the screen

MarqueeTextColor – (string) Hex Colors (example #0A0A0A)

MarqueeYPosition – (integer) vertical position of marquee text in pixels. Default is 0. Positioning is dependent on display resolution, for example a 1920 x 1200 display has MarqueeYPosition range of 0 (bottom) to 1200 (top).

ScrollMarquee – (boolean) value for scrolling of marquee text across the screen

SelectSingleMacVolume – (boolean) for behavior to bypass Boot Runner whenever there is only a single Mac volume on the system

ShowRestartButton – (boolean) option to display a restart button at bottom of selection screen

ShowShutdownButton – (boolean) option to display a shutdown button at bottom of selection screen

Timeout – (integer) Time in seconds from when the OS X login screen is displayed without keyboard/mouse activity before returning to the Boot Runner selection screen.

WindowLevel – (integer) BR default is screen saver window level (9).  Can specify 0 – 9.  See window level constants: http://apple.co/1aRwMh1

 ** Note: there is no key for “Show Boot Runner in Menu Bar”. To automate or remotely enable the Boot Runner Menu Bar, launch “/Applications/Utilities/Boot Runner Config.app/Contents/Resources/Boot Runner Menu.app”

  …

<?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>PayloadContent</key>
    <array>
      <dict>
        <key>PayloadContent</key>
        <dict>
          <key>com.twocanoes.bootrunner</key>
          <dict>
            <key>Forced</key>
            <array>
              <dict>
                <key>mcx_preference_settings</key>
                <dict>
          <key>AutomaticallySelectVolume</key>
          <string>Windows</string>
          <key>CustomBackgroundPath</key>
          <string>/Library/Desktop Pictures/Frog.jpg</string>
          <key>HiddenVolumeNames</key>
          <string>Linux</string>
          <key>MarqueeText</key>
          <string>Thank your for trying Boot Runner!</string>
          <key>MarqueeTextPosition</key>
          <integer>1</integer>
          <key>SelectSingleMacVolume</key>
          <true/>
          <key>ShowUnmountedVolumes</key>
          <string>disk0s3</string>
          <key>VolumeDescriptions</key>
          <array>
             <dict>
                 <key>VolumeDescriptionRTF</key>
                 <string>e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcY29jb2FydGYxMTg3XGNvY29hc3VicnRm
MzcwCntcZm9udHRibFxmMFxmc3dpc3NcZmNoYXJzZXQwIEhlbHZldGljYTt9Cntc
Y29sb3J0Ymw7XHJlZDI1NVxncmVlbjI1NVxibHVlMjU1O30KXHBhcmRcdHg3MjBc
dHgxNDQwXHR4MjE2MFx0eDI4ODBcdHgzNjAwXHR4NDMyMFx0eDUwNDBcdHg1NzYw
XHR4NjQ4MFx0eDcyMDBcdHg3OTIwXHR4ODY0MFxwYXJkaXJuYXR1cmFsXHFjCgpc
ZjBcYlxmczI4IFxjZjAgXHVsIFx1bGMwIE9wZXJhdGluZyBTeXN0ZW0KXGIwXGZz
MjQgXApcdWxub25lIE1pY3Jvc29mdCBXaW5kb3dzXAp9</string>
              <key>VolumeDescriptions</key>
              <string>/Library/VolumeDescriptions/bootcamp.rtf</string>
              <key>VolumeLabel</key>
              <string>Restore</string>
              <key>VolumeName</key>
              <string>disk0s3</string>
              <key>VolumeType</key>
              <integer>1</integer>
             </dict>
          </array>
              </dict>
            </dict>
            </array>
        </dict>
      </dict>
      <key>PayloadEnabled</key>
      <true/>
      <key>PayloadIdentifier</key>
      <string>MCXToProfile.f04eae87-b68e-4677-9f08-62224636f147.alacarte.customsettings.0882cb47-941a-4cec-ba9e-954464aa99a5</string>
      <key>PayloadType</key>
      <string>com.apple.ManagedClient.preferences</string>
      <key>PayloadUUID</key>
      <string>0882cb47-941a-4cec-ba9e-954464aa99a5</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
    </dict>
  </array>    
  <key>PayloadDescription</key>
  <string>Included custom settings:com.twocanoes.bootrunner</string>
  <key>PayloadDisplayName</key>
  <string>MCXToProfile: com.twocanoes.bootrunner</string>
  <key>PayloadIdentifier</key>
  <string>com.twocanoes.bootrunnertest</string>
  <key>PayloadOrganization</key>
  <string></string>
  <key>PayloadRemovalDisallowed</key>
  <true/>
  <key>PayloadScope</key>
  <string>System</string>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadUUID</key>
  <string>f04eae87-b68e-4677-9f08-62224636f147</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
  </dict>
</plist>

 …

 

Managing Boot Runner: Installing a Configuration Profile back to top^

Installation of a configuration profile for Boot Runner can be done via the Finder, the profile command in the Terminal application, or via a client management system such as Profile Manager on OS X Server (10.7 or later).

1. To manually install a configuration profile, double click on the configuration profile to install via Profile System Preference Pane.

2. To install a configuration profile via the command line, use the profiles command in the Terminal application.

 

 …

 

sudo profiles -I -F ~/Desktop/com.twocanoes.bootrunner.mobileconfig

 …

 

3. The configuration profiles can be deployed using Profile Manager on OS X Server or other client management utilities that support deploying configuration profiles.

 

Managing Boot Runner: Managed Client for OS X back to top^

Boot Runner can be managed with Managed Client for OS X policy inside of a directory service such as OS X Server, Active Directory or LDAP. Boot Runner contains a full manifest of all available keys to make management easy.

To start managing with Managed Client for OS X:

  1. Open Workgroup Manager and connect to your Directory Service.
  2. Select the computer, computer group, or computer list to apply settings.
  3. Select Preferences
  4. Select Details
  5. Click the padlock to authenticate
  6. Click + to add a Preference Manifest and choose /Library/PrivilegedHelperTools/Boot Runner. Boot Runner will now be added to the list.

 

Managing Boot Runner: Managed Client for OS X back to top^

  1. Select the computer, computer list or computer group and click the pencil to edit the Boot Runner settings and apply policy.
  2. Expand “Always” and click “New Key”
  3. Select the key you wish to manage and add details.
  4. When done, click Apply Now, then Done.

See the list of available keys, type and values from the list of above. 

 

Managing Boot Runner: Logging Options back to top^

Boot Runner logs messages via the Apple System Logger.  Normally, it only logs informational messages and any critical messages.  However, you can temporarily turn on verbose logging and see more verbose messages.  To temporarily turn on verbose logging, open the Terminal application and enter:

 

…

sudo syslog -c 0 -d

…

This will allow OS X to start logging all messages (-d is for debug).  Open Console in the Utilities folder to view the Boot Runner log messages.  Filtering on the term “BRLog” will display only Boot Runner application messages.

To turn off debug logging, open the Terminal application and enter:

… 

sudo syslog -c 0 off

…

This turns off debug logging and returns to normal system logging.  Restarting the Mac will also reset to normal (non-debug) logging.

 

Additional Options back to top^

Boot Runner supports some additional options.

  1. If there is a file at the top of a volume named “.bootrunner.rtf” (note the period at the start of the name) and a volume description is defined via a policy, configuration profile or preference, text contained in the RTF file will be shown as the description text in the Boot Runner Selection Screen.
  2. OS X will unmount any volumes contained on removable drives when the user logs out, and will also unmount them if the removable drives are plugged when the Login Window appears. In order to see external drives at the Login Window, run the following defaults command:   sudo defaults write /Library/Preferences/SystemConfiguration/autodiskmount
  3. To set Windows to reboot on logout, create a script that contains the command shutdown -r -f -t 0. In gpedit.msc, go to User Configuration > Windows Settings > Scripts and add the script to the Logoff item.