Custom Scripts Overview

By Joe Wyatt-Borner

Learn about the Custom Script Library Item and how to leverage the power of custom Scripts

Custom Scripts can be deployed to run on your enrolled Mac devices. The Kandji Agent is leveraged to run Custom Scripts on Mac computers. Kandji has a collection of example scripts available in our GitHub repository.

Execution Frequency

Depending on the script you want to deploy, you can specify if it will be run once, at every check-in, once per day, or run on-demand from Self Service. 

  • Install once per device: The script will run once per device. If the script fails, it will automatically try again on the following check-ins until it is successful.
  • Run every 15 min: The script will be run at each check-in (~ every 15 minutes).
  • Run daily: The script will be run every 24 hours based on the previous run time.
    • The Custom Script Library Item can additionally be offered via Self Service in the above 3 scenarios
  • Run on-demand from Self Service: The script will never be run automatically and will only be offered as an optional item from Self Service. After the item is executed, the Run button will be relabelled Run again.

Default Shell and Executing User

Understand what shells and interpreters can be specified for a custom script, as well as what user custom scripts are run as. 

  • Any shell or interpreter that exists on the Mac computer can be specified in your custom script. If a shell or interpreter is not specified, the default shell is used (/bin/sh). 
  • Custom scripts run by the Kandji Agent are always executed as the root user.

Exit Codes and Outputs

Understand how script exit codes affect Custom Scripts' status and what output from Custom Scripts is collected and stored.

  • If a script exits with an exit code of 0, it is considered a passing result. If it exits with an exit code other than 0, it is considered an Alert/Failure.
  • Stdout and Stderr are recorded in the script's audit information, which can be found on the device status page or custom script status page. 

Remediation and Restart options

Understand what a remediation script is and how the restart option works within Custom Scripts. 

  • A remediation script allows the main Audit Script to be leveraged as a true audit script to check for system configuration or application state. If this audit script exits with an exit code other than 0, this is considered an audit failure, and the remediation script will then be run.
    • If the remediation script then exits with an exit code of 0, the status of the library item for that device will be Remediated. If the remediation script fails, the library item status for that device will be Alert.
  • The restart option allows you to force a restart after a successful script execution. When this option is selected, the user will receive a restart timer from the Kandji Agent menu bar application. This timer will be a 5-minute restart timer if the item was initiated from Self Service or a 30-minute restart timer if initiated in another way such as during a check-in. The restart option will behave differently based on the use of a remediation script.
    • If a Remediation script is being leveraged, when the Remediation script exits 0, this will trigger the restart countdown. 
    • If a Remediation script is not being leveraged, when the Audit script exits 0, this will trigger the restart countdown.