-
Notifications
You must be signed in to change notification settings - Fork 17
FAQs
Here, we aim to compile a list of frequently asked questions (FAQs) regarding python-jamf. This section will provide answers and information to address some of the common queries you may have about this tool.
To obtain the version of python-jamf installed, execute the following command:
jctl --version
The output will be similar to the following:
jctl --version
jctl 1.1.19
python_jamf 0.8.3 (0.8.3 required)
This command will display the version of python-jamf along with any relevant information, such as the required version for proper functionality.
Since python-jamf is a Python library and doesn't have a dedicated man page or help documentation, you can refer to its project's official website or GitHub repository for information on the available options and functionality. The documentation should provide detailed explanations, usage examples, and descriptions of the various features and methods provided by the python-jamf library.
python-jamf is a specific Python library that provides a set of tools and functions for interacting with Jamf Pro, a popular device management platform for Apple devices. With python-jamf, 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, python-jamf 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 python-jamf 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.
An API, or Application Programming Interface, in the context of Jamf Pro, refers to a set of rules and protocols that allow different software applications to interact and communicate with the Jamf Pro device management platform. The Jamf Pro API provides a standardized way for developers to programmatically access and manipulate data and functionality within Jamf Pro.
By utilizing the Jamf Pro API, MacAdmins (or developers) can create custom scripts, applications, or integrations that interact with Jamf Pro to automate administrative tasks, retrieve information about managed devices, update settings, deploy software packages, and perform various other operations.
The Jamf Pro API is typically based on REST (Representational State Transfer) principles, which means it uses standard HTTP methods (such as GET, POST, PUT, DELETE) to perform operations on resources (such as devices, configurations, policies) represented by URLs.
Developers can make HTTP requests to the appropriate endpoints provided by the Jamf Pro API, including authentication credentials and relevant data in the requests, and receive responses in formats like JSON or XML. These responses contain the requested data or confirmation of the performed action.
By leveraging the Jamf Pro API, MacAdmins (or developers) can integrate Jamf Pro with other systems, build custom interfaces, automate workflows, and extend the capabilities of Jamf Pro to suit the specific needs of their organization.
Jamf Pro currently has support for two APIs, "Jamf Pro Classic" and "Jamf Pro Universal" APIs, or Application Programming Interfaces.
The Classic API is based on the standard User Accounts and Groups functionality of Jamf Pro. It supports Basic Authentication and utilizes the CRUD (Create, Read, Update, Delete) privileges to correspond with the HTTP methods: POST, GET, PUT, and DELETE. The Classic API offers a range of endpoints and functionality for interacting with Jamf Pro. You can refer to the Classic API Overview documentation for more detailed information.
Announced at JNUC 2016, the Jamf Pro Universal (aka Jamf Pro) API, also known as the Jamf Pro API, serves as the underlying framework for displaying information in much of the Jamf Pro web interface. The Jamf Pro API is intended to eventually surpass the functionality of the Classic API. However, according to the information available at that time, the Jamf Pro API project was still under development and would take time to update and incorporate all the features of the Classic API. The python-jamf Python library currently integrates the Classic API due to the Jamf Pro API's limited features and functionality.
However, there were plans to integrate support for the Jamf Pro Universal API in the future, once it met the requirements and became more finalized and usable.
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.
Note, that we have transitioned to the python-jamf and jctl projects to rely on the jps-api-wrapper project for records interaction via XML or JSON. We have kept the python-jamf API code in the project to allow others to continue using it if needed, but we plan on removing it at a future date.
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 python-jamf, 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 python-jamf:
Run mkdir python-jamf ; cd python-jamf to create and navigate to the folder.
Execute pipenv install python-jamf to install python-jamf and its dependencies.
Activate the virtual environment by running pipenv shell. This will ensure that you are using the installed python-jamf 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 python-jamf and jctl 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 python-jamf and jctl 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 poplular 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 python-jamf 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
pipfileby using the command:cd python-jamf - Upgrade the
python-jamfmodule and its requirements by executing the command:pipenv update python-jamf - Reactivate the virtual environment by running:
pipenv shell
These steps will upgrade python-jamf to the latest version and ensure that your virtual environment is using the updated version.
To uninstall python-jamf 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
pipfileby using the command:cd python-jamf - Uninstall the
python-jamfmodule by executing the command:pipenv uninstall python-jamf - Similarly, uninstall
jctlby running:pipenv uninstall jctl
After completing these steps, the python-jamf and jctl modules will be removed from the Python libraries within your virtual environment.