Skip to content

Installing

Jump to bottom
James Reynolds edited this page Nov 19, 2021 · 40 revisions

Quick Start

Installing

sudo pip3 install python-jamf
  • On your Jamf Pro server create a Jamf Pro API User
  • Configure: conf-python-jamf
  • Enter hostname, username, and password
  • Test: conf-python-jamf -t
  • You should see something like {'accounts': {'groups': None, 'users': {'user': {'id': '1', 'name': 'james'}}}}

For more details on the steps see below...

Uninstalling

sudo pip3 uninstall python-jamf

Detailed Instructions

Requirements

Tested operating systems: macOS 10.14, macOS 10.15, macOS 11, and CentOS 7. It probably works on lots of other operating systems.

Jamf Pro is a commercial product. This project interacts with Jamf Pro and there's not much use for it without Jamf Pro. We are assuming you already have this all set up.

Python3. This project does not work with the Python 2.7 that comes with macOS and we aren't going to support it. macOS does not come with python3 (and probably never will). You must install Python3. There are several ways to install it.

You can download and install a python3 package, or it is installed when you install Anaconda, or you can use Homebrew. This is how you install it with Homebrew.

brew install python3

Make sure it works.

python3
pip3 --version

Install

Install python-jamf.

sudo pip3 install python-jamf

pip will install python-jamf and its requirements. You'll see something like this.

% sudo pip3 install python-jamf
Collecting python-jamf
  Downloading python_jamf-0.7.2-py3-none-any.whl (118 kB)
     |████████████████████████████████| 118 kB 4.4 MB/s
Collecting keyring>=23.0.0
  Downloading keyring-23.2.1-py3-none-any.whl (33 kB)
Collecting requests>=2.24.0
  Downloading requests-2.26.0-py2.py3-none-any.whl (62 kB)
     |████████████████████████████████| 62 kB 2.6 MB/s
Collecting importlib-metadata>=3.6
  Downloading importlib_metadata-4.8.2-py3-none-any.whl (17 kB)
Collecting jeepney>=0.4.2
  Downloading jeepney-0.7.1-py3-none-any.whl (54 kB)
     |████████████████████████████████| 54 kB 8.3 MB/s
Collecting SecretStorage>=3.2
  Downloading SecretStorage-3.3.1-py3-none-any.whl (15 kB)
Collecting zipp>=0.5
  Downloading zipp-3.6.0-py3-none-any.whl (5.3 kB)
Collecting urllib3<1.27,>=1.21.1
  Downloading urllib3-1.26.7-py2.py3-none-any.whl (138 kB)
     |████████████████████████████████| 138 kB 25.5 MB/s
Collecting idna<4,>=2.5
  Downloading idna-3.3-py3-none-any.whl (61 kB)
     |████████████████████████████████| 61 kB 17.5 MB/s
Collecting certifi>=2017.4.17
  Downloading certifi-2021.10.8-py2.py3-none-any.whl (149 kB)
     |████████████████████████████████| 149 kB 38.3 MB/s
Collecting charset-normalizer~=2.0.0
  Downloading charset_normalizer-2.0.7-py3-none-any.whl (38 kB)
Collecting cryptography>=2.0
  Downloading cryptography-35.0.0-cp36-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.manylinux_2_24_aarch64.whl (3.2 MB)
     |████████████████████████████████| 3.2 MB 44.0 MB/s
Collecting cffi>=1.12
  Downloading cffi-1.15.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (448 kB)
     |████████████████████████████████| 448 kB 10.5 MB/s
Collecting pycparser
  Downloading pycparser-2.21-py2.py3-none-any.whl (118 kB)
     |████████████████████████████████| 118 kB 57.1 MB/s
Installing collected packages: pycparser, cffi, zipp, jeepney, cryptography, urllib3, SecretStorage, importlib-metadata, idna, charset-normalizer, certifi, requests, keyring, python-jamf
Successfully installed SecretStorage-3.3.1 certifi-2021.10.8 cffi-1.15.0 charset-normalizer-2.0.7 cryptography-35.0.0 idna-3.3 importlib-metadata-4.8.2 jeepney-0.7.1 keyring-23.2.1 pycparser-2.21 python-jamf-0.7.2 requests-2.26.0 urllib3-1.26.7 zipp-3.6.0

Uninstall

sudo pip3 uninstall python-jamf

This will remove python-jamf. It will look something like this.

% sudo pip3 uninstall python-jamf
Found existing installation: python-jamf 0.7.2
Uninstalling python-jamf-0.7.2:
  Would remove:
    /usr/local/bin/conf-python-jamf
    /usr/local/lib/python3.10/site-packages/jamf/*
    /usr/local/lib/python3.10/site-packages/python_jamf-0.7.2.dist-info/*
    /usr/local/lib/python3.10/site-packages/tests/*
Proceed (Y/n)? y
  Successfully uninstalled python-jamf-0.7.2

Enter "y" and python-jamf will be removed.

If downloaded via other means you will have to find the package and delete it manually.

Create an API User

To use python-jamf you'll need to create a service account that will interact with the Jamf Pro API. It is recommended to create a user name that describes its purpose, something like python-jamf or jctl, which you can do in the Jamf Pro administrative web interface located at:

Settings > System Settings > Jamf Pro User Accounts and Groups

Configure

Use conf-python-jamf to set python-jamf specific credentials. Or, if you already have ~/Library/Preferences/com.github.autopkg.plist configured, python-jamf will use those credentials. If you don't have that but /Library/Preferences/com.jamfsoftware.jamf.plist exists python-jamf will use that for the server and username and it will ask for a password. If you don't have either of those, python-jamf will ask for a password every time it runs unless you use conf-python-jamf to set python-jamf specific credentials.

conf-python-jamf

Enter hostname, username, and password.

% conf-python-jamf
Hostname (don't forget https:// and :8443): https://jamf.example.com:8443
Username: apiuser
Password: [hidden]
2021-11-19 21:11:15,100:     INFO: jamf.config.Config - save(): saving: /Users/james/Library/Preferences/edu.utah.mlib.jamfutil.plist

On macOS the settings are stored in ~/Library/Preferences/edu.utah.mlib.jamfutil.plist. On Linux the settings are stored in ~/.edu.utah.mlib.jamfutil.plist.

Test the Connection

conf-python-jamf -t

If you've done everything correctly you'll see something like this.

% conf-python-jamf -t
{'accounts': {'groups': None, 'users': {'user': {'id': '1', 'name': 'james'}}}}

If the username or password is incorrect you'll see this.

% conf-python-jamf -t
401 Unauthorized

If your server is incorrect you'll see this.

% conf-python-jamf -t
HTTPConnectionPool(host='jamfpro', port=8443): Max retries exceeded with url: /JSSResource/accounts (Caused by NewConnectionError('<urllib3.connection.HTTPConnection object at 0xffff905c9e10>: Failed to establish a new connection: [Errno 111] Connection refused'))

If you are using the containerized Jamf Pro server then the server setting is "http://jamfpro" unless you're also running python-jamf inside of a container. If you're running python-jamf inside of one of the containers in this project the server is "http://jamfpro:8080".

Keychain Support via keyring

To improve credential security we use the Python keyring library. This provides an easy way to access the system keyring service from python. The keyring uses the macOS Keychain or Linux KWallet.

Keychain and KWallet are encrypted files that securely stores your account names and passwords for applications, servers, websites, and confidential information such as credit card numbers or bank account PIN numbers. conf-python-jamf will securely store your Jamf Pro server URL, API user account name, and password in either the macOS Keychain or Linux KWallet.

Because of this you will get prompts asking you to allow Python to access your Keychain. If you don't want to give Python access use the AutoPkg preferences to store your Jamf Pro server and credentials. Note, these credentials are not encrypted and can be read by any of your processes on your computer.

defaults write com.github.autopkg JSS_URL https://jamf.example.com
defaults write com.github.autopkg API_USERNAME apiUser
defaults write com.github.autopkg API_PASSWORD apiPass

Testing the installation in a Python script

Start a Python REPL interpreter.

python3

Create an api with the following command:

import jamf
api = jamf.API()

If you haven't configured python-jamf yet, it will ask for credentials.

Hostname (don't forget https:// and :8443): https://jamf.example.com:8443
Username: [API USER ACCOUNT]
Password: [API USER PASSWORD]

Then pull some data from the server and print it out.

from pprint import pprint
pprint(api.get('accounts'))

You should see some output like this.

{'accounts': {'groups': None, 'users': {'user': {'id': '1', 'name': 'james'}}}}

Are you excited? Try getting these as well.

pprint(api.get('computers'))
pprint(api.get('computergroups'))
pprint(api.get('policies'))
pprint(api.get('categories'))

Using python-jamf can view everything available at the following url on your jamf server.

https://jamf.example.com:8443/api/

Note, jctl is limited by certain record types, python-jamf is not.

jctl

To install jctl, see the instructions on the jctl wiki.

Table of Contents

Clone this wiki locally