FAQs - univ-of-utah-marriott-library-apple/jctl GitHub Wiki

Here, we aim to compile a list of frequently asked questions (FAQs) regarding jctl. This section will provide answers and information to address some of the common queries you may have about this tool.

To obtain a comprehensive list of installed applications and their respective versions on your Macs, you can utilize the following command:

jctl computers -S apps

Executing this command will generate a CSV file containing information about the computers, installed applications, and their corresponding versions. Please note that this command may take some time to execute due to the processing involved.

If you wish to narrow down the search by specifying certain computers, you can utilize the following command:

jctl computers -r regex -S apps

Here is an abbreviated example of the output you can expect:

application,version,spare-01,spare-02,spare-04
"/Applications/Utilities/Adobe Sync/CoreSyncExtension/ACCFinderBundleLoader.app","5.14.2.1",X,,
"/Applications/Utilities/Adobe Sync/CoreSyncExtension/ACCFinderBundleLoader.app","5.14.3.1",,,

To check the installed version of jctl, use the following command:

jctl --version

For example, the output will resemble the following:

jctl --version
jctl 1.1.19
python_jamf 0.8.3 (0.8.3 required)

This command will display the version of jctl and any additional relevant information, such as the required version of the python_jamf library.

To view the available options for jctl, you can use the help command. By entering jctl --help or jctl -h, you will be able to display the help page and explore the different arguments that can be used with the jctl command.

For example...

jctl --help
usage: jctl [-h] [-c [CREATE ...]] [-u UPDATE] [-d] [-S [SUB_COMMAND ...]] [-i [ID ...]]
            [-n [NAME ...]] [-r [REGEX ...]] [-s SEARCHPATH] [-l] [-p PATH] [-j]
            [--quiet-as-a-mouse] [-C CONFIG] [-v] [--use-the-force-luke]
            [--andele-andele]
            [record]

positional arguments:
  record                Valid Jamf Records are: advancedcomputersearches,
                        advancedmobiledevicesearches, advancedusersearches, buildings,
                        byoprofiles, categories, classes, computerconfigurations,
                        computerextensionattributes, computergroups, computerreports,
                        computers, departments, directorybindings,
                        diskencryptionconfigurations, distributionpoints, dockitems,
                        ebooks, ibeacons, jsonwebtokenconfigurations, ldapservers,
                        macapplications, managedpreferenceprofiles,
                        mobiledeviceapplications, mobiledevicecommands,
                        mobiledeviceconfigurationprofiles,
                        mobiledeviceenrollmentprofiles, mobiledeviceextensionattributes,
                        mobiledeviceinvitations, mobiledeviceprovisioningprofiles,
                        mobiledevices, netbootservers, networksegments,
                        osxconfigurationprofiles, packages, patchexternalsources,
                        patchinternalsources, patchpolicies, patchsoftwaretitles,
                        peripherals, peripheraltypes, policies, printers,
                        removablemacaddresses, scripts, sites, softwareupdateservers,
                        userextensionattributes, usergroups, users, vppaccounts,
                        vppassignments, vppinvitations, webhooks

optional arguments:
  -h, --help            show this help message and exit
  -c [CREATE ...], --create [CREATE ...]
                        Create jamf record (e.g. '-n <rec_name> [other]')
  -u UPDATE, --update UPDATE
                        Update jamf record (e.g. '-u general={} -u name=123')
  -d, --delete          Delete jamf record
  -S [SUB_COMMAND ...], --sub-command [SUB_COMMAND ...]
                        Execute subcommand for record
  -i [ID ...], --id [ID ...]
                        Search for id matches
  -n [NAME ...], --name [NAME ...]
                        Search for exact name match
  -r [REGEX ...], --regex [REGEX ...]
                        Search for regular expression matches
  -s SEARCHPATH, --searchpath SEARCHPATH
                        Search for a path (e.g. '-s general/id==152'
  -l, --long            List long format
  -p PATH, --path PATH  Print out path (e.g. '-p general -p serial_number')
  -j, --json            Print json (for pretty pipe to `prettier --parser json`)
  --quiet-as-a-mouse    Don't print anything
  -C CONFIG, --config CONFIG
                        path to config file
  -v, --version         print version and exit
  --use-the-force-luke  Don't ask to delete. DANGER! This can delete everything!
  --andele-andele       Don't pause 3 seconds when updating or deleting without
                        confirmation. DANGER! This can delete everything FAST!

For examples please see https://github.com/univ-of-utah-marriott-library-apple/jctl/wiki/jctl

jctl is a Python tool that provides a set of tools and functions for interacting with Jamf Pro, a popular device management platform for Apple devices. With jctl, MacAdmins (or developers) can automate and streamline administrative tasks related to managing Apple devices, such as macOS and iOS devices, within an organization.

By default, jctl logs information to the console. However, MacAdmins (or developers) have the flexibility to configure the logging output to different destinations, such as files or external log management systems, by utilizing the logging configuration options provided by the Python logging module. Python includes a logging module in its standard library, which offers a versatile framework for generating log messages within Python programs.

However, due to prioritization and constraints in terms of time and resources, we have not dedicated efforts to support logging with jctl so far.

If you consider this feature to be crucial, please submit an issue on the GitHub repository. We will make an attempt to address this functionality in the future.

python-jamf is a Python library specifically designed for accessing the Jamf Pro Classic API. It enables programmatic access to data on a Jamf Pro server, allowing integrations with external utilities and systems. The library provides a class that directly maps to the API, handling URL requests, authentication, and conversion between XML/JSON and Python dictionaries/lists. With python-jamf, users have transparent access to the underlying API functionality and can easily work with the data and methods it provides.

jctl is a command line tool that allows users to perform CRUD operations on a Jamf Pro or Jamf Cloud server. It provides automation capabilities for repetitive tasks and offers additional options not found in the web GUI. jctl is closely tied to python-jamf, which is a Python library specifically designed for the Jamf Pro Classic API and serves as the primary driver for jctl.

pkgctl is a tool designed to simplify package management tasks. It focuses on packages, particularly those that require frequent updates, such as web browsers. By examining server data from the perspective of each package, pkgctl identifies relevant policies, patch software titles, patch policies, and computer groups associated with them. It provides an interactive mode where users can select package groups and effortlessly transfer policies, patch policies, and computer groups between different package versions. Additionally, pkgctl offers various formats for displaying information, such as viewing groups, usage, and performing clean-up operations. Using regular expressions, pkgctl can also set package definitions based on matching patch software titles and their versions.

patch.py is a deprecated script that was created to automate the patching process. It originally focused on patch management, including managing installer packages, assigning packages to patch definitions, updating versions, and supporting version release branching. However, most of the functionality has been replaced by various jctl subcommands, and the package upload feature stopped working around Jamf Pro 10.28.0. As a replacement, users are advised to refer to jamf-upload. It's important to note that certain functionalities within patch.py are specific to the Marriott Library's environment and may not work correctly in other environments. Although the tool is currently included, there are plans to remove it completely in the future.

conf-python-jamf is a tool used to configure credentials for python-jamf. It allows users to set specific credentials for python-jamf or utilize existing configurations stored in ~/Library/Preferences/com.github.autopkg.plist. If the latter is unavailable, conf-python-jamf will check for /Library/Preferences/com.jamfsoftware.jamf.plist for server and username information, prompting for a password. If none of these configurations are found, python-jamf will require a password input with each run, unless conf-python-jamf is used to set python-jamf specific credentials.

The keyring Python library is utilized to enhance credential security by accessing the system keyring service from Python. It supports macOS Keychain and Linux KWallet, encrypted files that securely store account names and passwords for various applications, servers, and confidential information. With conf-python-jamf, users can securely store their Jamf Pro server URL, API user account name, and password in the keyring service. However, using the keyring may prompt for permission to access the Keychain, and if users prefer not to grant Python access, they can store the Jamf Pro server and credentials in AutoPkg preferences, which are not encrypted and accessible to all processes on the computer.

To successfully install and use jctl along with the required Python library python-jamf, it is necessary to have Python version 3.6 or later installed. It's important to note that Python 3.6 and Python 3.7 have reached their end-of-life status, as indicated on the Python developer web page. Therefore, it is recommended to have at least Python 3.8 installed, as a bare minimum, to ensure compatibility with jctl and python-jamf.

Installing Python on macOS can be confusing, but here are some key points to keep in mind. Starting with macOS 12.3, Python is no longer included, but you can install it using the Apple Command Line Developer Tools prompt or through the official Python installer from python.org. Anaconda and Homebrew are alternative options. Pay attention to the "python" and "python3" binaries; different installations may provide one or both. The PATH environment variable determines where the system looks for Python. Libraries like python-jamf have specific locations depending on the Python version. To avoid errors, ensure the correct Python version is used. Consider using a Python virtual environment like pipenv to manage dependencies and simplify the installation process.

See the Installing Python wiki page for more details.

To install jctl, it is recommended to use pipenv, which creates a virtual environment with a self-contained site directory containing Python and python-jamf.

pipenv is a package management tool used for creating and managing Python virtual environments and handling project dependencies. It combines the functionality of pip (the package installer) and virtualenv (a tool for creating isolated Python environments).

Here are the steps to install and configure jctl:

Run mkdir jctl ; cd jctl to create and navigate to the folder.

Execute pipenv install jctl to install jctl and its dependencies.

Activate the virtual environment by running pipenv shell. This will ensure that you are using the installed jctl within the virtual environment.

Create a Jamf Pro API User on your Jamf Pro server. Inside the virtual environment shell, run conf-python-jamf to configure the connection to the Jamf Pro server. Enter the hostname, username, and password as prompted.

After configuration, you can test the connection to the Jamf Pro server by running conf-python-jamf -t. If the configuration is successful, you should see a response similar to {'accounts': {'groups': None, 'users': {'user': {'id': '1', 'name': 'MY_NAME'}}}}.

Currently, it is not possible to install jctl and python-jamf using an installer package, unless you create a custom package installer yourself. We recommend using pipenv for the installation process instead. It's worth noting that jctl and python-jamf are primarily intended for MacAdmin systems or servers rather than widespread deployment across multiple Mac devices, making installer packages less necessary. Our team has not prioritized the development of installer packages for these tools at this time.

An Apple installer package, commonly known as a .pkg file, is a file format used on macOS for software installation. It is a container that includes all the necessary files, scripts, and metadata required to install an application or package on a macOS system. And is a popular installation method used by Apple, 3rd party developers and MacAdmins.

If you consider this feature to be crucial, please submit an issue on the GitHub repository. We will make an attempt to address this functionality in the future.

To upgrade jctl to the latest version within your virtual environment, you can follow these steps:

• Exit the current virtual environment session and ensure that the session is saved.
• Navigate to the folder containing your pipfile by using the command: cd jctl
• Upgrade the jctl module and its requirements by executing the command: pipenv update jctl
• Reactivate the virtual environment by running: pipenv shell

These steps will upgrade jctl to the latest version and ensure that your virtual environment is using the updated version.

To uninstall jctl from your virtual environment, you can follow these steps:

• Exit the current virtual environment session and ensure that the session is saved.
• Navigate to the folder containing your pipfile by using the command: cd jctl
• Uninstall the jctl module by executing the command: pipenv uninstall jctl
• Similarly, uninstall python-jamf by running: pipenv uninstall python-jamf

After completing these steps, the jctl and python-jamf modules will be removed from the Python libraries within your virtual environment.