Skip to content

Creating Overrides

Jump to bottom
Joe Workman edited this page Sep 10, 2020 · 8 revisions

AutoPkg Overrides

Recipe Overrides allow for additional package automation steps or configuration changes from a parent recipe. Creating overrides of a particular package enables the JC-AutoPkg-Importer to ingest any .pkg recipe. An override configured to run the JC-AutoPkg-Importer, would run the same parent recipe and pass variables into the JC-AutoPkg-Importer to create commands in JumpCloud and upload a .pkg file to an AWS S3 Bucket.

To create an override of a package, use the make-override verb to generate an override file.

autopkg make-override Firefox.pkg
Override file saved to /Users/Administrator/Library/AutoPkg/RecipeOverrides/Firefox.pkg.recipe.

The override file is saved to /Users/Administrator/Library/AutoPkg/RecipeOverrides/Firefox.pkg.recipe and can be modified to run the JC-AutoPkg-Importer by adding the "Process" block lines directly below a ParentRecipe key string pair.

<key>ParentRecipe</key>
<string>com.github.autopkg.AutoPkgGitMaster</string>

Copy and paste the following code block into a recipe override below the "ParentRecipe" key string pair

<key>Process</key>
<array>
    <dict>
        <key>Processor</key>
        <string>JumpCloudImporter</string>
        <key>Arguments</key>
        <dict>
            <key>JC_DIST</key>
            <string>AWS</string>
            <key>AWS_BUCKET</key>
            <string>jcautopkg</string>
            <key>JC_SYSGROUP</key>
            <string>AutoPkg-%NAME%-%version%</string>
            <key>JC_TYPE</key>
            <string>auto</string>
        </dict>
    </dict>
</array>

The XML block instructs the recipe to run the JC-AutoPkg-Importer processor during each recipe run. Additional Argument key/string pairs can be specified to customize the type of command and system group to be generated.

Example Override Documentation

The process of creating a new override and using the JC-AutoPkg-Importer is demonstrated with the following Open Office example:

Use AutoPkg to search for a community recipe

Running autopkg search openoffice should yield similar results like the below example. Since the JC-AutoPkg-Importer ingests .pkg recipes, there are two possible .pkg recipes I can use to install OpenOffice on target systems.

autopkg search openoffice

Name                           Repo                     Path
----                           ----                     ----
OpenOffice.sccm.recipe         cgerke-recipes           Applications/OpenOffice.sccm.recipe
OpenOffice.pkg.recipe          hjuutilainen-recipes     OpenOffice/OpenOffice.pkg.recipe
OpenOffice.munki.recipe        hjuutilainen-recipes     OpenOffice/OpenOffice.munki.recipe
OpenOffice.install.recipe      hjuutilainen-recipes     OpenOffice/OpenOffice.install.recipe
OpenOffice.download.recipe     hjuutilainen-recipes     OpenOffice/OpenOffice.download.recipe
OpenOffice.jss.recipe          jss-recipes              OpenOffice/OpenOffice.jss.recipe
Open Office.jss.recipe         novaksam-recipes         Open Office/Open Office.jss.recipe
OpenOffice.download.recipe     novaksam-recipes         Recipes - Download/OpenOffice.download.recipe
OpenOffice.pkg.recipe          novaksam-recipes         Recipes - pkg/OpenOffice.pkg.recipe
OpenOffice.filewave.recipe     peshay-recipes           OpenOffice/OpenOffice.filewave.recipe
ChemDoodle.munki.recipe        wholtz-recipes           ChemDoodle/ChemDoodle.munki.recipe

To add a new recipe repo, use 'autopkg repo-add <repo name>'

Add remote repository and make overrides

In this example, between novaksam-recipes and hjuutilainen-recipes, the hjuutilainen repository was updated more recently. It's often the case that duplicate recipes for popular software titles are packaged by several community recipe supporters. Picking a recipe to override is sometimes a matter of preference, last updated timestamps or familaiarty with the reposity owner. As always, trust but verify your package sources. Elliot Jordan's presentation on How (Not) To Do Bad Things With AutoPkg is an excellent resource on the matter of verifying your AutoPkg sources.

To import hjuutilainen-recipes repository run: autopkg repo-add hjuutilainen-recipes

autopkg make-override OpenOffice.pkg

Override file saved to /Users/admin/Library/AutoPkg/RecipeOverrides/OpenOffice.pkg.recipe

Customize the override

With the override saved in the admin user's RecipeOverride folder, the OpenOffice.pkg.recipe can be customized to run the JC-AutoPkg-Importer processor. When customizing recipes, it's helpful to rename the recipe to something unique. For any of the recipes intended to run the JC-AutoPkg-Importer processor, rename the recipe to include the term "jumpcloud". Either rename the override file with a text editor or command. In the example below the override was renamed to "OpenOffice.jumpcloud.recipe"

mv /Users/admin/Library/AutoPkg/RecipeOverrides/OpenOffice.pkg.recipe /Users/admin/Library/AutoPkg/RecipeOverrides/OpenOffice.jumpcloud.recipe

AutoPkg tip you can automate this step with the autopkg "make-override" verb. Running autopkg make-override OpenOffice.pkg -n OpenOffice.jumpcloud would specify the name change when making the override.

Add the Processor

Open the "/Users/admin/Library/AutoPkg/RecipeOverrides/OpenOffice.jumpcloud.recipe" file in a text editor that supports XML. This specific recipe should look something like this by default:

<?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>Identifier</key>
    <string>local.pkg.OpenOffice</string>
    <key>Input</key>
    <dict>
        <key>LANGUAGE</key>
        <string>en-US</string>
        <key>NAME</key>
        <string>OpenOffice</string>
    </dict>
    <key>ParentRecipe</key>
    <string>io.github.hjuutilainen.pkg.OpenOffice</string>
    <key>ParentRecipeTrustInfo</key>
    <dict>
        <key>non_core_processors</key>
        <dict/>
        <key>parent_recipes</key>
        <dict>
            <key>io.github.hjuutilainen.download.OpenOffice</key>
            <dict>
                <key>git_hash</key>
                <string>9c31d064520bb3838a0828071444e1367e1323b7</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.hjuutilainen-recipes/OpenOffice/OpenOffice.download.recipe</string>
                <key>sha256_hash</key>
                <string>2af7669c40bebdf173ef465f716aa37ff3b406f0818f90bf7f91cd4d4ccd026f</string>
            </dict>
            <key>io.github.hjuutilainen.pkg.OpenOffice</key>
            <dict>
                <key>git_hash</key>
                <string>50c594cfa99319f9efe5b932e607449dd218d684</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.hjuutilainen-recipes/OpenOffice/OpenOffice.pkg.recipe</string>
                <key>sha256_hash</key>
                <string>f52edc5108cc8f77421d4797cd7fe933b06e494a0e9804c473815b5cf3d94d63</string>
            </dict>
        </dict>
    </dict>
</dict>
</plist>

To instruct the recipe override to invoke the JC-AutoPkg-Importer processor, add the following XML lines below the Parent Recipe key/string pair:

<key>Process</key>
<array>
    <dict>
        <key>Processor</key>
        <string>JumpCloudImporter</string>
        <key>Arguments</key>
        <dict>
            <key>JC_DIST</key>
            <string>AWS</string>
            <key>AWS_BUCKET</key>
            <string>jcautopkg</string>
            <key>JC_SYSGROUP</key>
            <string>AutoPkg-%NAME%-%version%</string>
            <key>JC_TYPE</key>
            <string>auto</string>
        </dict>
    </dict>
</array>

The correctly formatted override file should look like the file below:

<?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>Identifier</key>
    <string>local.pkg.OpenOffice</string>
    <key>Input</key>
    <dict>
        <key>LANGUAGE</key>
        <string>en-US</string>
        <key>NAME</key>
        <string>OpenOffice</string>
    </dict>
    <key>ParentRecipe</key>
    <string>io.github.hjuutilainen.pkg.OpenOffice</string>
    <key>Process</key>
    <array>
        <dict>
            <key>Processor</key>
            <string>JumpCloudImporter</string>
            <key>Arguments</key>
            <dict>
                <key>JC_DIST</key>
                <string>AWS</string>
                <key>AWS_BUCKET</key>
                <string>jcautopkg</string>
                <key>JC_SYSGROUP</key>
                <string>AutoPkg-%NAME%-%version%</string>
                <key>JC_TYPE</key>
                <string>auto</string>
            </dict>
        </dict>
    </array>
    <key>ParentRecipeTrustInfo</key>
    <dict>
        <key>non_core_processors</key>
        <dict/>
        <key>parent_recipes</key>
        <dict>
            <key>io.github.hjuutilainen.download.OpenOffice</key>
            <dict>
                <key>git_hash</key>
                <string>9c31d064520bb3838a0828071444e1367e1323b7</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.hjuutilainen-recipes/OpenOffice/OpenOffice.download.recipe</string>
                <key>sha256_hash</key>
                <string>2af7669c40bebdf173ef465f716aa37ff3b406f0818f90bf7f91cd4d4ccd026f</string>
            </dict>
            <key>io.github.hjuutilainen.pkg.OpenOffice</key>
            <dict>
                <key>git_hash</key>
                <string>50c594cfa99319f9efe5b932e607449dd218d684</string>
                <key>path</key>
                <string>~/Library/AutoPkg/RecipeRepos/com.github.autopkg.hjuutilainen-recipes/OpenOffice/OpenOffice.pkg.recipe</string>
                <key>sha256_hash</key>
                <string>f52edc5108cc8f77421d4797cd7fe933b06e494a0e9804c473815b5cf3d94d63</string>
            </dict>
        </dict>
    </dict>
</dict>
</plist>

Save the recipe override before running the recipe.

Run the recipe override

To run the recipe override, run:

autopkg run OpenOffice.jumpcloud.recipe

The terminal window should display similar output:

Processing OpenOffice.jumpcloud.recipe...
WARNING: OpenOffice.jumpcloud.recipe is missing trust info and FAIL_RECIPES_WITHOUT_TRUST_INFO is not set. Proceeding...
========== JumpCloud AutoPkg Importer ==========
Importer Version: 0.1.1
Package Name: OpenOffice
Importer Package: /Users/jworkman/Library/AutoPkg/Cache/local.pkg.OpenOffice/downloads/OpenOffice.dmg
Importer Type: auto
AWS Bucket: jcautopkg
=================================================
JumpCloud API Key:
System group does not exist, creating group:
THE GROUP ID IS: 5ed6a6d21f24751b14c973e3
THE GROUP NAME IS: AutoPkg-OpenOffice-4.1.7
auto
============== BEGIN SYSTEM QUERY ===============
OpenOffice not found on system: 5d66e0ac51db1e789bb17c77
adding 5d66e0ac51db1e789bb17c77 to 5ed6a6d21f24751b14c973e3
OpenOffice not found on system: 5e0e19831bc893319ae068b6
adding 5e0e19831bc893319ae068b6 to 5ed6a6d21f24751b14c973e3
OpenOffice not found on system: 5e6a566bf6231239260efadf
adding 5e6a566bf6231239260efadf to 5ed6a6d21f24751b14c973e3
OpenOffice not found on system: 5e84b68732f2d77d12f73622
adding 5e84b68732f2d77d12f73622 to 5ed6a6d21f24751b14c973e3
OpenOffice found on system : 5e90f19ecc99d210ecb3406c
=============== END SYSTEM QUERY ================
=================================================
============== BEGIN VERSION QUERY ==============
system:5e90f19ecc99d210ecb3406c OpenOffice does not require updating
4.1.7 already on latest version... 4.1.7
system 5e90f19ecc99d210ecb3406c not in group 5ed6a6d21f24751b14c973e3
=============== END VERSION QUERY ===============
=================================================
============== BEGIN COMMAND CHECK ==============
Command does not exist, creating command
Command created: AutoPkg-OpenOffice-4.1.7
Uploading: OpenOffice-4.1.7.pkg to AWS bucket: jcautopkg
=============== END COMMAND CHECK ===============
=================================================
========== BEGIN COMMAND ASSOCIATIONS ===========
Associating command: 5ed6a6e0f40ff301983886d1 to system group: 5ed6a6d21f24751b14c973e3
=========== END COMMAND ASSOCIATIONS ============
=================================================
Summary of system to group changes
{'5d66e0ac51db1e789bb17c77': '5ed6a6d21f24751b14c973e3',
 '5e0e19831bc893319ae068b6': '5ed6a6d21f24751b14c973e3',
 '5e6a566bf6231239260efadf': '5ed6a6d21f24751b14c973e3',
 '5e84b68732f2d77d12f73622': '5ed6a6d21f24751b14c973e3'}

The following new items were downloaded:
    Download Path
    -------------
    /Users/admin/Library/AutoPkg/Cache/local.pkg.OpenOffice/downloads/OpenOffice.dmg

The following packages were built:
    Identifier                 Version  Pkg Path
    ----------                 -------  --------
    org.openoffice.script.pkg  4.1.7    /Users/admin/Library/AutoPkg/Cache/local.pkg.OpenOffice/OpenOffice-4.1.7.pkg

Table of Contents

Configuration Steps

Using the Importer

Troubleshooting

Clone this wiki locally