More
We "highly" recommend that you set up a Jamf Pro development server testing python-jamf module or anything experimental or major changes on a development server before implementing it on your production server. In case something unexpected happens it only happens development server and NOT your production server.
For example, if you are a Jamf Cloud customer you can get a "sandbox" server that you can experiment and test things before moving to production. Or for on-premise instances, you get a "sandbox" license that you can set up in your server infrastructure.
Using Docker Desktop on a Mac system, you can set up a Jamf Pro "sandbox" using docker-compose, and you can quickly set up and teardown without additional server infrastructure.
See the following GitHub repository here for instructions on this process.
Or here is an in-depth presentation, Docker for Beginners by James Reynolds at the University of Utah, MacAdmins meeting.
If you want to test & experiment with python-jamf before promoting it to be installed into your system site directories, a virtual environment provides one option.
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 (which matches the version of the binary that was used to create this environment) and can have its own independent set of installed Python packages in its site directories.
- Install pipenv:
sudo pip3 install pipenv - 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 - On your Jamf Pro server create a Jamf Pro API User
For more detailed information on the setup process on the quick setup page.
Next, to configure your Jamf Pro server credentials, enter the following command:
From inside the activated shell.
% conf-python-jamf
Hostname (don't forget https:// and :8443): https://jamf.example.edu: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
From any command line and outside the activated shell.
- First cd to the python-jamf Pipelock file location.
cd ./python-jamf
% pipenv run conf-python-jamf
Hostname (don't forget https:// and :8443): https://jamf.example.edu: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
Next, to test the setup of python-jamf and your Jamf Pro server credentals & settings, enter the following command:
From inside the activated shell.
% conf-python-jamf -t
{'accounts': {'groups': None, 'users': {'user': {'id': '1', 'name': 'richard'}}}}
From any command line and outside the activated shell.
First cd to the python-jamf Pipelock file location.
cd ./python-jamf
% pipenv run conf-python-jamf -t
{'accounts': {'groups': None, 'users': {'user': {'id': '1', 'name': 'richard'}}}}
For more details on usage, please see Testing Installation with Python
After you are done testing the python-jamf virtual environment, you can exit with the following command:
% deactivate
If you want to start the python-jamf virtual environment in the future, change directory to the location you store your virtual environments and then enter the command:
% source python-jamf-env/bin/activate
(python-jamf-env)
When a new version of Python Jamf comes out it is simple to upgrade the virtual environment to the latest version.
- Exit the current 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
To uninstall Python Jamf from the virtual environment.
- Exit the current 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.
The following doesn't work as of 2020/12.
cd python-jamf
# runs all tests
python3 -m unittest discover -v
# run tests individually
python3 -m python-jamf.tests.test_api
python3 -m jamf.tests.test_config
python3 -m jamf.tests.test_convert
python3 -m jamf.tests.test_packageIf you see an error that says something like SyntaxError: invalid syntax, check to see if you're using python3.
Receiving errors using different aspects of python-jamf?
Here are some common errors and how to fix them:
With Python having different locations where site-packages can be stored, it can be difficult to make sure that it is using the correct version. python-jamf is located in one of the site-package directories. To find the location we have to look at how Python uses site-packages. Python has a hierarchical list of directories it checks for the library.
The list can be found by using Python's site command.
python3 -m site
This produces the list of site-package directories Python checks.
% python3 -m site
sys.path = [
'/Users/[UserAccountName]/Documents/GitHub/jctl',
'/Library/Frameworks/Python.framework/Versions/3.8/lib/python38.zip',
'/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8',
'/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/lib-dynload',
'/Users/[UserAccountName]/Library/Python/3.8/lib/python/site-packages',
'/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages',
]
USER_BASE: '/Users/[UserAccountName]/Library/Python/3.8' (exists)
USER_SITE: '/Users/[UserAccountName]/Library/Python/3.8/lib/python/site-packages' (exists)
ENABLE_USER_SITE: True
The top directory in the list is the first place that Python tries to find the particular site-package. Perform a list on the directory and see if you find jamf or python-jamf there. "jamf" was the old name that was installed pre-0.4.0. Continue down the list until you have reached where pip has installed python-jamf for you.
To figure out where pip has installed python-jamf for you, use this command:
pip show python-jamf
In location it will display where PIP has installed `python-jamf``.
% pip show python-jamf
Name: python-jamf
Version: 0.6.9
Summary: Python wrapper for Jamf Pro API
Home-page: https://github.com/univ-of-utah-marriott-library-apple/python-jamf
Author: The University of Utah
Author-email: mlib-its-mac@lists.utah.edu
License: UNKNOWN
Location: /Users/[UserAccountName]/.local/lib/python3.8/site-packages
Requires: keyring, requests
Required-by: jctl
By the time that you have reached the pip installed directory, the other python-jamf should have been discovered.
Please see the Roadmap in the jctl wiki.
Please see the Contribute page in the jctl wiki.
- Sam Forester
- James Reynolds
- Topher Nadauld
- Richard Glaser
- Tony Williams
- O'Ryan Hampton