How to issue Restart Mobile Device command en masse and on predefined schedule leveraging Jamf Pro API.

Have you ever been tasked with restarting your mobile device fleet on a schedule? Do you set yourself task reminders and issue the command using the Jamf Pro admin console?

What if there was a better way? There is...

It involves several items. I'll provide you the base recipe to get started.

• API role
• API client
• Script
• LaunchDaemon

Step 1: Setting up the API role and client

First, we will want to create a new API role in Jamf Pro:

• In Jamf Pro navigate to Settings > System > API roles and clients, API Roles, select "+ New"
• Provide it a name (example: "API Role to issue restart command to mobile devices")
• Assign the following privileges: Create Moble Devices, Read Mobile Devices, Send Mobile Device Restart Device Command, Read User

Next we will want to create a new API client in Jamf Pro, and assign it the role we have created for it:

• In Jamf Pro navigate to Settings > System > API roles and clients, API Clients, select "+ New"
• In the Display Name provide a description (example: "API Client to restart mobile devices"), and from the list of roles select the previously created role. We can leave the Access Token Lifetime at the default setting.
• Save and Enable API client

Generate the Client ID and Secret. The window presented should look similar to this:

2. Creating the Script and setting proper access

The Baseline script is below:

#!/bin/bash

### revision 1.0
### This script is to be used to mass restart Apple TVs and/or other mobile devices



# Jamf Pro server address
# API client ID
# API client secret

# this API role name is: insert role name here for your notes
# this API client name is: insert clinet name here for your notes

### the API user has the following rights
### Create Mobile Devices, Read Mobile Devices, Send Mobile Device Restart Device Command, Read User


# these are examples only
baseURL="SuperDuperOrg.jamfcloud.com/"
client_id="9d31a790-32e7-4745-b4ef-7b0bfa277518"
client_secret="NamrGWkvs9V0hv4maQcNSTQMKiz114CHc1giktWbu-EredBgSNaSFcTCiVjy1iBr"



access_token=$(curl --silent --location \
	--request POST "https://$baseURL/api/oauth/token" \
	--header "Content-Type: application/x-www-form-urlencoded" \
	--data-urlencode "client_id=$client_id" \
	--data-urlencode "grant_type=client_credentials" \
	--data-urlencode "client_secret=$client_secret" | plutil -extract "access_token" raw -o - -)

# Uncomment the next line for troubleshooting if necessary, to test out the API user credentials, sanity check
# echo $access_token

sleep 1


# Provide list of Jamf Pro devices below
deviceIDList="101
305
350
1188"

for deviceID in $deviceIDList
do
	curl -s -X POST https://$baseURL/JSSResource/mobiledevicecommands/command/RestartDevice/id/$deviceID -H "Content-Type: application/xml" -H "Authorization: Bearer $access_token" 
	
	echo ""
	echo $deviceID
	echo ""
done

        

In the script you will need to change/update the following information:

• baseURL: address name of your Jamf Pro Server
• client_id: generated from the previous step
• client_secret: generated from the previous step

as well as provide list of device IDs. In the example script we are issuing the RestartDevice command to the devices with the following device IDs: 101, 305, 350, 1188.

Note that there are multiple methods to obtain a device ID of a Jamf Pro client. You may pull up a device inventory record and see it in the Inventory, General tab under the field label: Jamf Pro Mobile Device ID:. Another method is to view the website/web browser address for the device record and record the number from there. You may also create a smart or static group or a saved search and obtain the information that way, provided you are capturing this information under Inventory Display. To change those settings, navigate to: Settings, Device management, Inventory display. Or you may receive this information via a pregenerated or emailed Report.

Before we get too far ahead, I would like to make a few suggestions and tips.

• Do not write code in Ms. Word or other document with rich text.
• You may use the textedit app (when using plain text) or another text editor to read and write code; I have been using apps such as ATOM or BBEDIT in the past. In the last several years switched to CodeRunner. The app is available in the Mac App Store as well as from the vendor. This last version will let you run in 14 day trial mode.
• An advantage of CodeRunner is you can execute the script right in the app.
• Last tip on the script is use the "#" to comment out lines you don't want the script to execute. Use these lines as notes for yourself and your team-mates. I suggest to uncomment the "echo $access_token" line to verify that your server URL, client ID and client secret are correct. The output will be a long string of characters or an error.

Below are two outputs of the script thus far:

We need to save the file as shell script with extension .sh into an easily accessible location. For simplicity will use the /users/shared folder.

Now that we have the script where we want it need to change the owner and set correct permissions to the script file. To accomplish this task we will use the Terminal app and type the following commands, we substitute the /path/to/file with the actual file path (example: "/Users/Shared/IssureRestartCommand.sh"

sudo chown root:wheel /path/to/file        

The above command will set the owner to user root, and group wheel.

sudo chmod 755 /path/to/file        

The above command will set the following permissions: The root owner will have the Read, Write, and Execute rights. The wheel group will have the Read, and Execute rights. Everyone else will have same level of access as the wheel group.

3. Creating and loading the Launch Daemon

Launch Daemons are preference files and in some ways are similar to Launch Agents. If you have an application or another call to action when you sign in to your computer you may possibly be utilizing a Launch Agent. If you have an action being performed at a scheduled time even when not signed in you can be leveraging Launch Daemon.

The Baseline Launch Deamon is below

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>com.SuperDuperorg.Weekly.ATVRestart.daemon</string>
    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>/Users/Shared/IssueRestartCommand.sh</string>
	  </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>8</integer>
        <key>Minute</key>
        <integer>05</integer>
        <key>Weekday</key>
        <integer>2</integer>
    </dict>
    <key>StandardErrorPath</key>
    <string>/Users/Shared/RestartCommand_error.log</string>
    <key>StandardOutPath</key>
    <string>/Users/Shared/RestartCommand_log.log</string>
  </dict>
</plist>        

In the script you will need to change/update the following information:

• The label which is currently named com.SuperDuperorg.Weekly.ATVRestart.daemon to something unique
• The line showing the path to the script file
• The schedule. Currently it is set to run on the following schedule: Weekly on day 2 - Tuesday at 8:05 AM local time.

Save the file as a .plist file extension and save to your Desktop. Then copy it to /Library/LaunchAgents folder.

There are few more steps but we are getting close to the finish line...

First will need to set the correct permissions to the file, and then load the file into memory.

Just like earlier will use the chown command to set the correct ownership

sudo chown root:wheel /path/to/file        

and similarly, how we did earlier will set the correct permissions

sudo chmod 644 /path/to/file        

If you have noticed, the rights set are slightly different.

The above command will set the following permissions: The root owner will have the Read, and Write rights. The wheel group will have the Read rights. Everyone else will have same level of access as the wheel group.

Next, will need to load the Daemon into memory by running the following command:

sudo launchctl bootstrap system /path/to/file        

To confirm the Daemon has loaded we can use the following command:

sudo launchctl list        

This will give us a list of all the currently loaded services. We can limit this list by levering pipe "|" (it is the key to the right of the [] keys and above the return key (on a US standard keyboard layout). The command will search limit and if we use the name file from the .plist file com.SuperDuperorg.Weekly.ATVRestart.daemon we can run the following command:

sudo launchctl list | grep Weekly.ATVRestart        

When it comes to launch agents and launch daemons and labels, they need to be unique for them to work properly.

Closing statements...

This guide can be used as a stepping stone.

I do not recommend running this task as a Jamf Pro policy, or locally on your everyday device. Instead, create a dedicated Task Server computer which is securely stored in your server room.

When creating API roles and clients use the least amount of privileges.

The credentials used in this example have been created in a test/dev environment and have been invalidated.

In our field there is always more to learn. My motto is You don't know what you don't know. There is always more to learn. The possibilities are endless!

There are other ways to accomplish this task. I'm presenting one solution that you can use as a baseline to get things off the ground.

I'm adding several online resources which I found helpful working with this topic and they are:

• https://www.launchd.info
• https://scriptingosx.com
• https://gingerscripting.com/launchdaemons/

I hope you find this guide helpful. Thank you.