Skip to content

Installing

Jump to bottom
Richard Glaser edited this page Mar 10, 2022 · 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, macOS 12, 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.

Upgrading

Upgrading python-jamf is easy if you installed it via pip. pip is the Package Installer for Python.

To upgrade python-jamf run the following command:

% sudo pip3 install --upgrade python-jamf

For example, it will look something like this:

% sudo pip3 install --upgrade python-jamf
Requirement already satisfied: python-jamf in /opt/anaconda3/lib/python3.8/site-packages (0.7.3)
Requirement already satisfied: requests>=2.24.0 in /opt/anaconda3/lib/python3.8/site-packages (from python-jamf) (2.25.1)
Requirement already satisfied: keyring>=23.0.0 in /opt/anaconda3/lib/python3.8/site-packages (from python-jamf) (23.2.1)
Requirement already satisfied: importlib-metadata>=3.6 in /opt/anaconda3/lib/python3.8/site-packages (from keyring>=23.0.0->python-jamf) (3.10.0)
Requirement already satisfied: zipp>=0.5 in /opt/anaconda3/lib/python3.8/site-packages (from importlib-metadata>=3.6->keyring>=23.0.0->python-jamf) (3.4.1)
Requirement already satisfied: idna<3,>=2.5 in /opt/anaconda3/lib/python3.8/site-packages (from requests>=2.24.0->python-jamf) (2.10)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /opt/anaconda3/lib/python3.8/site-packages (from requests>=2.24.0->python-jamf) (1.26.4)
Requirement already satisfied: certifi>=2017.4.17 in /opt/anaconda3/lib/python3.8/site-packages (from requests>=2.24.0->python-jamf) (2020.12.5)
Requirement already satisfied: chardet<5,>=3.0.2 in /opt/anaconda3/lib/python3.8/site-packages (from requests>=2.24.0->python-jamf) (4.0.0)

Version

To display the version of python-jamf installed, run the following command:

jctl --version

For example, it will look something like this:

jctl --version
jctl 1.1.15
python_jamf 0.7.3 (0.6.9 required)

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: [MyAPIUser]
Password: [hidden]
2021-11-19 21:11:15,100:     INFO: jamf.config.Config - save(): saving: /Users/[UserAccountName]/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.

Configure Help

To display help use the help command with conf-python-jamf you can enter the following arguments:

conf-python-jamf --help or conf-python-jamf -h

For example:

% conf-python-jamf -h
usage: conf-python-jamf [-h] [-H HOSTNAME] [-u USER] [-p PASSWD] [-C PATH] [-P] [-t]

optional arguments:
  -h, --help            show this help message and exit
  -H HOSTNAME, --hostname HOSTNAME
                        specify hostname (default: prompt)
  -u USER, --user USER  specify username (default: prompt)
  -p PASSWD, --passwd PASSWD
                        specify password (default: prompt)
  -C PATH, --config PATH
                        specify config file (default ~/Library/Preferences/edu.utah.mlib.jamfutil.plist)
  -P, --print           print existing config profile (except password!)
  -t, --test            Connect to the Jamf server using the config file

Custom Configuration Preferences

You configure your server, username, and password with conf-python-jamf. If you create or copy the preferences to a different location, you can manually tell jctl to use the custom location with -C.

This will look in the current folder for a file named "localhost.plist" and use the server and username stored in that file. It will use that server and username to look in the Keychain for the password.

jctl -C /path/to/localhost.plist [SUBCOMMAND]
Production & Development Preferences

For example, if you wanted to setup two preferences, one, for a development server and another for your production server you could do the following:

Define Default Preferences

First, you should decide which server you want to setup as default and which server(s) you want setup as custom preference(s): like development, testing, production, etc., with your jctl setup.

Create Custom Preference with Path

Next, use the -C arguement with conf-python-jamf with path to custom preference location:

Development Server Custom Preference

conf-python-jamf -C /path/to/custom-prefs/my.dev.server.plist

Production Server Custom Preference

conf-python-jamf -C /path/to/custom-prefs/my.prod.server.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 Installation with Python

To test the installation with python, first, 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