Can you imagine a world without needing to make your own packages, searching sites for updated installers, and being able to reproduce the same identical process over and over? Such a place for Mac Admins exists. The icing on the cake is the amount of coding or API knowledge you need to accomplish this is minimal. The goal of this document is to take a freshly imaged Mac Computer and have an installation of Autopkgr up and running with a few basics packages to your JSS (both on Prem and Cloud) in under 60 minutes. The best option would be reading all the material first and following along once you’re sure you can accomplish everything listed.
Disclaimer, this is based on the state of Jamf Pro and AutoPkgr in December 2019. As of the time publishing this, these steps will work as long as your Jamf Pro instance is able to be reached by the AutoPkgr computer. You might need to expose end points or make changes to your JSS’s structure to enable this to work for your orginization (please do your own due diligence). This document assumes you are running Jamf Cloud, with a public endpoint, a computer with access to the internet to install AutoPkgr on, and permissions to the JSS to create a API user with a password. Your mileage may vary.
Getting Started
Let’s dive straight into this. You’ll need a computer that you can setup and run this on. While you can do this on your own production machine, the best setup would be an older machine that’s off to recycling or ideally a Mac Mini you can set out of sight and out of mind. Anything with more than 4gb of memory (ideally 8gb-16gb), a sufficiently sized storage drive (256gb-1tb is ideal, and SSD over Spinning drive is better), and a network connection. Everything else can be basically ignored on this configuration as there is no need for i7’s or hex cores. My current setup is a base model 2012 Mac Mini with 8gb ram, and 500gb SSD I swapped myself. Create a local user account and log in. No need for nearly anything else.
Now we need to download and install AutoPkgr. AutoPkgr can be found here: Lindegroup on Github and by clicking the latest release link in the readme text. The current version is v1.5.1. Download and open the DMG file. Drag it to your applications folder and authenticate as needed.
Now let’s open AutoPkgr. Authorize Gatekeeper to open the file. Input your password to install the AutoPkgr helper tool by authenticating.
Once it’s finished configuring, you’ll reach a screen with a few tab options and two main buttons, Install AutoPkg and Install Git. We’ll need to install both of them.
Click Install AutoPkg. This is how AutoPkgr will work. AutoPkgr is just the GUI for running AutoPkg. Autopkg is the tool that’s doing all the heavy lifting behind the scenes, but for a new user, having this GUI on top of the command line tools is an outstanding starting point. Authorize as needed and wait for the install to finish the light to turn green. The current version of AutoPkg is 1.4.1.
Select Install Git. Git is a required component to download and manage your repos for AutoPkgr as well as updating in the background. If you’re unfamiliar with Git, that’s ok. The Gui helps you along the way. Eventually learning and understanding some of Git and uploading your own recipes in the future is ideal, but that’s a task for another day. Authorize again and wait for the light to light up. Git’s current version is 2.2.1.
Ok! One more piece to install for the initial configuration. Select the Folders & Integrations tab and let’s install JSSimporter. JSSImporter is the part that’s going to handle all the negotiations between AutoPkgr and your JSS. The current version 1.0.5 supports both Jamf Pro (onprem) and Jamf Cloud.
Communicating with the Jamf Pro Server
Great! We’ve installed everything we need to be successful locally, but we’ll still need a way to talk to the server. Now you could be a mad lad and input your own account and password into AutoPkgr and provide that computer full administrator access…or we could create an access account with far less permissions. Let’s do the ladder of the two options here.
This works if your company allows you to create users outside the standard realm. Some places only allow AD/LDAP users, or maybe something created in Okta. Whatever the case is, you’ll need to figure out that path and make a local user in the JSS. Just make sure to tell InfoSec “All the cool companies are doing it”. They should OK it without question once they know they aren’t cool anymore. Nothing hurts these guys more than being labeled “that one uncool InfoSec team”. (/s)
Log to your JSS and head to Management Settings > System Settings > Jamf Pro User Accounts & Groups.
Let’s select + New and start building our new API account. Make them a Standard User. If prompted, skip the LDAP search and instead make a new user.
Input the following information:
Username: “AutoPkgr” or something memorable for what you’re doing here.
Privilege Set: Custom
Access Status: Enabled
Full Name: Not Required
Email Address: Not Required
Password: *********** (and save it somewhere your team can access it if needed!)
Verify Password: **hunter2**
Force change at next login: UNCHECKED
Great! Now lets provide our API user some permissions. They need the following. No more. (Possibly less)
Jamf Pro Server Objects
apply a check if one of these is listed:
Create = C
Read = R
Update = U
Delete = D
Categories - C/R/U
Computer Extension Attributes - C/R/U
Configurations - C/R/U
File Share Distribution Points - C/R/U
macOS Configuration Profiles - C/R/U
Packages - C/R/U
Policies - C/R/U
Scripts - C/R/U
Smart Computer Groups - C/R/U
Static Computer Groups - C/R/U
Jamf Pro Server Settings
Cloud Distribution Point - Read
Time to Save! We now have our API account configured and AutoPkgr installed. Let’s get them talking.
Head back to AutoPkgr and head to the Folders & Intergrations Tab again. Select Configure JSSimporter.
Input your JSS URL. For Jamf Cloud users, it’s just the https://COMPANYNAME.jamfcloud.com address. For on prem, it’ll be whatever you need here plus :8443/ on the end so it can communicate through the port to the server. Remember, this is specifically your JSS Server address, not the distribution point (That’s below)
Input your username and password for the API account your created. Select Connect and make sure it can talk to the server. If the light turns green, we’re doing great! (If not, recheck everything above and try it again. Remember, your computer needs to be able to reach the JSS server. Verify ACLs and permissions on the network too as needed.)
Now we need to configure our cloud distribution point. For Jamf Cloud users, you’ll select CDP (Cloud Distribution Point). No further configuration should be needed if you’re using the Jamf Cloud as your distribution point.
For on Prem, you’ll either be selecting JDS or one of the other options. This is tricky to map out everything in this short tutorial, so you can work with you local team or Jamf TAM for help on this one. They should be able to identify your configuration and help you find the right data to input. Save and Close!
The AutoPkgr Process
There is one last QOL setting to select before we leave this tab. Select Configure AutoPkg and at the very bottom select Recipe/Override editor to TextEdit or your preferred text editing program. Save and Close. You’ll see why we did this shortly.
Select the Notifications tab. Check the box for Enable macOS Notifications. Nothing else needed on this tab at this time. Come back later and setup your Slack integration or setup email notifications.
Select the Repos & Recipes tab. Welcome to your new home for a while. It’s broken up into two major areas. repos on the top, and recipes on the bottom. The quick and dirty here are repos hold the recipe files. Recipes tell AutoPkg what it needs to do for each application. Repos have been created by other community members to house different recipes they have created beyond just the standard pool you see here. Some people might have one part of a recipe, and you’ll need all the pieces to construct an entire installer through AutoPkg.
A recipe usually has 4 parts. Download, Pkg, JSS, and Override. There are other parts that exist, but we’ll be focusing on these 4 today. Without diving down a whole other tangent, there is a good video that explains how recipes are written found on Youtube. It’s pretty technical, but it’s a nice watch when you have time and little more understanding of how AutoPkg and AutoPkgr works.
So in order to configure AutoPkgr to start packing for you, we’ll need to find an application to bundle and upload. A great starting point would be Google Chrome. Everyone uses it, it seemingly updates every 12 minutes, and can require some management for most admins. On the right side of the window, let’s click Filter Recipes and search for “Chrome”.
Boom! One result! This is going to work out great! So now we’ll need to create an override to make a package. This override is required for your copy of AutoPkgr. It creates local instructions for AutoPkgr to follow, otherwise it’ll just go off to the internet somewhere. No one wants this. (It’s far more technical than that, but I’m keeping this high level for the moment).
Right click that Google Chrome.jss search result and ignore that Yellow caution sign! Select Create Override. Let’s give it a super fancy name! Add “-override” between Chrome and .jss. We’ll be naming all of our files like this. You’ll want them to be uniform so you can bulk search for them later. Click OK!
Oh no! An error. Could not find parent recipe…what? You just showed the entry when we searched the filer. What are these dir(s) listed? Relax. Remember when I said each part of recipe is typically 4 parts. We’ve only got 1 part of the 4, the JSS.recipe part. Let’s fix this problem.
We’ve got some useful clues as to where we need to look. On the error message you’ll notice some breadcrumbs that tell us a repo is missing. By default, only the Jss-recipes.git repo is installed. Right clicking on the entry and selecting Get Info will show us the Parent file seems to be missing. Not only do the 4 recipes parts exist, but they have a hierarchy. Typically it’s Download > PKG > JSS > Override. Se we’re at step 3. To fix steps 1 and 2, we’ll need to install the missing repo. Let’s search at the bottom of the AutoPkgr window for the missing recipe components on GitHub. Search again for the string “Chrome”.
Woah! A ton of results just appeared. Don’t feel overwhelmed. Remember our breadcrumbs from above? A tiny bit of scrolling should find those missing files. Boom, a repo called “recipes”. Let’s select that GoogleChrome.pkg option and choose Add Repo. Give it a moment to run some Git commands in the background and let those lights turn green. You’ll notice .download, .install, .munki and even other recipes will all turn green. This is because we pulled the full repo down, not just 1 file.
Now at the top of the AutoPkgr window you’ll see two illuminated repos, and in the future, you’ll likely have many many more. In our filter recipes box, type chrome again and look at all the results. We still need to make an override of that original .jss file. Find Google Chrome.jss and right click. Select Create Override. Name it “-override” right between Chrome and .jss again. Let’s let it run!
The very first time this time runs, it takes a bit longer than normal. It’s gotta download a file, unpack it, pack it, upload it, name it, create a jss policy for it. So many things. Let’s let it run it’s course. We’re almost there!
Anddddd…Another error message. But that’s ok too! This one is far more clear. Looks like we’re missing a group in the JSS to assign this to.
Let’s head into the Jamf Pro server again and just create a smart group named “Testing”. We won’t need any criteria at this time. Just an empty group. With that out of the way, it’s time to run that override again!
The spinning wheel stopped, our first AutoPkgr package is now ready! Head back to the Jamf Pro window and log in. Let’s head to Policies and take a look.
Well…there isn’t anything there…Doesn’t seem like AutoPkgr did anything. Let’s head to Management Settings > Computer Management > Packages and see if our package even appeared.
Ok, we see Google Chrome’s package listed there. So it seems like it’s partially working. Let’s fix the missing piece. The recipe is missing it’s instructions to create a JSS policy. First, lets delete the uploaded chrome package. Next, we’ll need to take a dive back over to AutoPkgr and open the recipe override for Chrome. Remember from earlier when we set the default editor? This is where it comes back into play.
Right click the Override and choose Open Recipe Override. You’ll be quickly bombarded with a wall of text. This is how AutoPkg works. It runs down the recipe file here committing instructions along the way. So reading down the document a bit, it seems like to create the policy it’s looking for something called “PolicyTemplate.xml”. We can manually make one…or, we can use the template that comes with one of our repos.
In AutoPkgr, right click the override and select Reveal in Finder. Now we’ll need to head up a folder level and look for a folder called RecipeRepos. This is where Git pulls these repos down to and stores them. Inside, we’ll have two folders. Select the com.github.autopkg.jss-recipes folder. Inside of that folder locate two files, PolicyTemplate.xml and SmartGroupTemplate.xml. Copy them both and paste them back into the original RecipeOverrides folder right next to your Google Chrome-override file.
No changes needed! Let’s run that override again! Right click it and send it on it’s way.
Your First AutoPkg Policy and Beyond
After a moment, the wheel will stop spinning again. Give your JSS a little time (1-2 mins at most) to finish making your policy and application available, and BAM! You now have a new entry in the Testing Category under Policies. This includes the uploaded package that AutoPkgr built, and all the configuration parameters we built. We’ll, we haven’t built any…yet. But pat yourself on the back! You’ve just uploaded your first app via AutoPkg!
So we’ve install AutoPkgr, configured Git, AutoPkg, and JSSimporter. We’ve fixed our missing parent recipes, fixed our missing Testing Smart Group, and added our PolicyTemplate and GroupPolicyTemplate files to our Overrides. Seems like a lot, huh? We aren’t done just yet. Let’s take a deeper look at PolicyTemplate to figure out what it’s really doing here.
Back in Finder, head back to back to the RecipeOverrides folder again (You can right click the Chrome Recipe and reveal in Finder). Right click the PolicyTemplate.xml file and open in Text Editor (or your weapon of choice).
Oof. More walls of text. But this should start making a little more sense. Let’s look at the variables contained in the file. Lots of <SOMETHING></SOMETHING> entries. Let’s connect the pieces together.
Opening up the file and your JSS side by side you can start to identify what each step is actually doing. Here is a quick breakdown of some of that functionality.
General
Name - JSS Policy Name leveraging the %PROD_NAME%
Enabled - Is the policy enabled? True/False
Frequency - Ongoing. Maybe we can use other options too?
Category - %POLICY_CATEGORY%
Self Service
User for Self Service - True/False?
Install Button Text - Install %VERSION%
Maintenance
Recon - True/False?
Ok, and now putting those pieces together, we can see each bracketed variable inputting those options into our JSS. So this file instructs AutoPkgr to build the policy using these settings. But some of these settings don’t really work for the way I’m building my environment. Let’s make some adjustments.
First, let’s create a copy of the file. That way we can always roll back if we need to. Name the original PolicyTemplateOLD.xml. The new file should just be PolicyTemplate.xml. Now let’s edit the new file.
For name, I prefer “Install - %PROD_NAME%”, and actually, I like to really leverage custom triggers in the JSS. I bet we can target that too. I know that the tag for it is <trigger_other> and I want it to be “install-%PROD_NAME%”. Don’t forget to close the tag with </trigger_other>. Let’s also add a <scope> area and include All Computers as true. I also want to update the install button to say something a little different, and I really don’t need a recon once everything is complete for this installer. Let’s save those changes!
Heading back into AutoPkgr, and let’s Filter Recipes for Firefox. Find the Firefox.jss recipe and let’s create an override. Now, check the box, right click the override, and select Open Recipe Override.
We’re going to tweak a few of the options inside this recipe to make it make a little more sense for us. I don’t need to to head into a Testing group in the JSS, and maybe I wanna update some of the description in Self Service. Save that Override, and run it. This way, we can compare Chrome and Firefox side by side.
Once it completes, and we’ve given it a minute or two to replicate, let’s head back into the JSS and see how it looks.
Looks nearly perfect! Maybe a few small changes to make it work for your org, but this is where we ultimately want to be.
Now let’s fix Chrome to look like Firefox. Delete the Chrome Policy and the Chrome Package from your JSS. Head back to AutoPkgr and let’s run the Chrome-override recipe!
Oops, almost had it. Forgot to update the Override recipe. Delete the entries from the JSS one more time and let’s head back into AutoPkgr. Right click the Override and Open Recipe Override. Make our changes to match Firefox. And once more, let’s run the recipe.
Boom! Looks nearly identical (minus the tiny differences between the two apps)!
And that’s my Zero to Go for AutoPkgr. In 60 minutes, we’ve conquered the basics to get you going! You’ll have a lot more work to do from here. Start simple. Start by working on the lowest hanging fruit. Web Browsers, Spotify, text editors, etc. Then as you get more and more comfortable, move onto more complex software. Search is your friend. So is Google. Many pieces of software are already AutoPkg’d. You’ll just need to find the right repo, connect it to your AutoPkgr, and create an Override.
A few things to note before we go!
Scheduling runs for AutoPkgr. You can schedule it to run once every few hours, once a day, once a week, etc. Get your setting dialed in first. Remember, all this depended on you manually doing this in the past. Even if you manually go in and kick it off once every week or two, it’s still less work on your plate.
Updating repos. You can update repos on each run. This is good and bad. Learn some more about Git before you dive into enabling that feature. That way if something changes, you’ll have a better understanding what’s happening.
Test. Test. Test. And when you think you’ve got it working, document everything. Everyone who might come after you will thank you immensely. And future you will too. ;) Just because you know it now, doesn’t mean 6 month from now you will.
Lastly, contribute! The more you use this, to more you’ll understand it. This is a barebones quick and dirty launch into it to help you have the confidence to continue. I’ve skipped over so many things. This software has reduce my weekly spend on handling updates manually myself. I’ve been able to set aside time to make documents like this because of it. You can do it too! Now that you’ve ready my guide, let’s do this! You’ve got everything you need to dive in and start AutoPkging.
Resources
AutoPkg Template Substitution Variables - https://github.com/jssimporter/JSSImporter/wiki/Template-Substitution-Variables
Creating recipes in AutoPkg 1.1 via Der Flounder - https://derflounder.wordpress.com/2019/05/29/using-autopkg-1-1s-recipe-template-creation-option/
Graham Pugh’s AutoPkg presentation at JNUC 2019 - https://grahamrpugh.com/2019/11/14/jamf-and-autopkg-jnuc2019-session.html
Powerpoint deck from 12/17/2019 Mac Admins meetup - Coming Soon.