Skip to content

Installing

Jump to bottom
Tophernad edited this page Apr 29, 2024 · 40 revisions

Quick Start

We recommend using pipenv to install python_jamf as pipenv creates a virtual environment with a self-contained site directory.

Installing python_jamf

  • Make a folder for your Pipfile: mkdir python_jamf ; cd python_jamf
  • Install Module & Requirements: pipenv install python_jamf
  • Activate the virtual environment: pipenv shell

Configure the Jamf Server

  • On your Jamf Pro server create a Jamf Pro API User
  • Inside of the virtual environment shell
  • Configure: conf-python-jamf
  • Enter the 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

To uninstall Python Jamf from the virtual environment.

  • Exit the current virtual environment session and allow the session to be saved.
  • Move to the folder that holds your Pipfile: cd python_jamf
  • Uninstall Module: pipenv uninstall python_jamf

The virtual environment is now missing Python Jamf from the Python libraries.

Detailed Instructions

Requirements

Tested operating systems: macOS 10.14, macOS 10.15, macOS 11, macOS 12, macOS 13, 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 setup.

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. We wrote a page on install Python because you might have issues.

Install

To install python_jamf, we recommend using pipenv. The pipenv module provides support for creating lightweight “virtual environments” with their own site directories, optionally isolated from system site directories. Each virtual environment has its own Python binary. The binary matches the version of the binary that was used to create the virtual environment. The virtual environment can have its own independent set of installed Python packages in its site directory. python_jamf can be installed outside of a virtual environment in the system python site directory as well.

Using pipenv to install python_jamf 

% sudo pip3 install pipenv

pip3 will install pipenv and its requirements. You'll see something like this.

% sudo pip3 install pipenv
Collecting pipenv
  Downloading pipenv-2023.2.18-py3-none-any.whl (2.9 MB)
     |████████████████████████████████| 2.9 MB 3.5 MB/s 
Collecting setuptools>=67.0.0
  Downloading setuptools-67.4.0-py3-none-any.whl (1.1 MB)
     |████████████████████████████████| 1.1 MB 15.9 MB/s 
Collecting virtualenv>=20.17.1
  Downloading virtualenv-20.19.0-py3-none-any.whl (8.7 MB)
     |████████████████████████████████| 8.7 MB 15.3 MB/s 
Requirement already satisfied: virtualenv-clone>=0.2.5 in /Users/cnadauld/Library/Python/3.9/lib/python/site-packages (from pipenv) (0.5.7)
Requirement already satisfied: certifi in /Library/Python/3.9/site-packages (from pipenv) (2022.9.24)
Requirement already satisfied: distlib<1,>=0.3.6 in /Users/cnadauld/Library/Python/3.9/lib/python/site-packages (from virtualenv>=20.17.1->pipenv) (0.3.6)
Requirement already satisfied: platformdirs<4,>=2.4 in /Users/cnadauld/Library/Python/3.9/lib/python/site-packages (from virtualenv>=20.17.1->pipenv) (2.5.2)
Requirement already satisfied: filelock<4,>=3.4.1 in /Users/cnadauld/Library/Python/3.9/lib/python/site-packages (from virtualenv>=20.17.1->pipenv) (3.8.0)
Installing collected packages: virtualenv, setuptools, pipenv
  Attempting uninstall: virtualenv
    Found existing installation: virtualenv 20.16.5
    Uninstalling virtualenv-20.16.5:
      Successfully uninstalled virtualenv-20.16.5
  Attempting uninstall: setuptools
    Found existing installation: setuptools 58.0.4
    Uninstalling setuptools-58.0.4:
      Successfully uninstalled setuptools-58.0.4
Successfully installed pipenv-2023.2.18 setuptools-67.4.0 virtualenv-20.19.0

Pipenv uses a Pipfile to store the virtual environment. Create a folder that will store the Pipfile.

% mkdir python_jamf ; cd python_jamf

Install PythonJamf Module & Requirements.

% pipenv install python_jamf
Creating a virtualenv for this project...
Pipfile: /Users/cnadauld/Documents/GitHub/Virtual Enviroment/python-jamf_doc/Pipfile
Using /usr/bin/python3 (3.9.6) to create virtualenv...
⠋ Creating virtual environment...created virtual environment CPython3.9.6.final.0-64 in 664ms
  creator CPython3macOsFramework(dest=/Users/cnadauld/.local/share/virtualenvs/python-jamf_doc-T7GJRPP9, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/cnadauld/Library/Application Support/virtualenv)
    added seed packages: pip==22.3.1, setuptools==66.1.1, wheel==0.38.4
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator

✔ Successfully created virtual environment!
Virtualenv location: /Users/cnadauld/.local/share/virtualenvs/python-jamf_doc-T7GJRPP9
Creating a Pipfile for this project...
Installing python_jamf...
Resolving python_jamf...
Installing...
Adding python_jamf to Pipfile's [packages] ...
✔ Installation Succeeded
Pipfile.lock not found, creating...
Locking [packages] dependencies...
Building requirements...
Resolving dependencies...
✔ Success!
Locking [dev-packages] dependencies...
Updated Pipfile.lock (9a19f7f193ae68c9a418a4b57ff03da4e11516eefe8d068a211895894d9808d0)!
Installing dependencies from Pipfile.lock (9808d0)...
To activate this project's virtualenv, run pipenv shell.
Alternatively, run a command inside the virtualenv with pipenv run.

Activate the virtual environment

% pipenv shell
Launching subshell in virtual environment...
 . /Users/cnadauld/.local/share/virtualenvs/python-jamf_doc-T7GJRPP9/bin/activate                                                                                          
cnadauld@GB-N6HN4NLXDQ python-jamf_doc %  . /Users/cnadauld/.local/share/virtualenvs/python-jamf_doc-T7GJRPP9/bin/activate

The virtual environment shell is now ready to be used. The virtual environment can be used via the activated shell or in any command line window by using the '% pipenv run' command.

Uninstall

To uninstall python_jamf from the virtual environment.

  • Exit the current virtual environment session and allow the session to be saved.
  • Move to the folder that holds your Pipfile: cd python_jamf
  • Upgrade Module & Requirements: pipenv uninstall python_jamf
  • Reactivate the virtual environment: pipenv shell

The virtual environment is now missing Python Jamf from the python libraries.

Upgrading

When a new version of Python Jamf comes out it is simple to upgrade the virtual environment to the latest version.

  • Exit the current virtual environment session and allow the session to be saved.
  • Move to the folder that holds your Pipfile: cd python_jamf
  • Upgrade Module & Requirements: pipenv update python_jamf
  • Reactivate the virtual environment: pipenv shell

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.

Make sure to run this command via the activated shell or with % pipenv run

% conf-python-jamf

Enter the 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 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 /path/to 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 set 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 set up as default and which server(s) you want set up as custom preference(s): like development, testing, production, etc., with your jctl setup.

You can setup Jamf Pro on localhost if you want to use Docker for testing a development server setup, see the Docker documentation for more details.

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 python_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