Patch Server for Jamf Pro Documentation

Transcription

1 Patch Server for Jamf Pro Documentation Release Bryson Tyrrell Jun 06, 2018

2

3 Contents 1 Change History 3 2 Using Patch Starter Script 7 3 Troubleshooting 9 4 Testing the Patch Server 11 5 Running as a Docker Container 13 6 Installation on macos 15 7 Installation on Ubuntu Server (16.04) 19 8 Add Your Patch Server to Jamf Pro 23 9 API Authentication Patch Server API Jamf Pro Patch API User Interface 41 HTTP Routing Table 47 i

4 ii

5 An open-source implementation of an external patch source for use with Jamf Pro (version 10.2+). User Interface Upload a New Software Title Upload Errors Update a Title s Version Other Title Actions Backup Patch Definitions Webhooks Contents 1

6 2 Contents

7 CHAPTER 1 Change History ( ) Fixed an issue where a mismatched or non-existing software title ID passed to /jamf/v1/software/<title>, <Title> would result in a 404 error response. The expected behavior is the invalid title ID to be omitted from the results (this is the behavior of both the official Jamf patch feed and CommunityPatch). Added documentation to describe resources for troubleshooting issues between Jamf Pro and a Patch Server ( ) macos quick install script. Updated daemon (removed KeepAlive). Updated documentation on managing the server using the Apache scripts ( ) Update a title s version from the UI. This updated contains a breaking API change! Previously, the /api/v1/title/<title>/version endpoint required JSON provided in the following format: { "Items": [ { "version": "", "releasedate": "", "standalone": true, "minimumoperatingsystem": "", "reboot": false, 3

8 } ] } "killapps": [], "components": [], "capabilities": [], "dependencies": [] The intent was to allow multiple versions to be posted at once (the underlying create_patch_objects function takes a list of patches), but for easier use and consistency with how the CommunityPatch API operates this has been changed. The endpoint will now expect only the JSON of the version itself: { } "version": "", "releasedate": "", "standalone": true, "minimumoperatingsystem": "", "reboot": false, "killapps": [], "components": [], "capabilities": [], "dependencies": [] ( ) Updated documentation including: Installation instructions and resources for Ubuntu Server A new Managing Your Patch Server section to help document workflows ( ) New webhook feature to allow the patch server to notify remote servers of changes to software titles via HTTP POSTs ( ) You can secure the API with token authentication (if you really want to) ( ) Because accurate and easy to read instructions are important. 4 Chapter 1. Change History

9 ( ) A minor renaming ( ) Make the GUI great(ish) again. The New Title button has been updated. It now prompts you to select a JSON file (the patch definition) and performs the upload. Validation is still performed on the uploaded file as with the API. The new /api/v1/backup feature is available in the GUI. Click the Backup button to trigger. The View button for a software title has been moved to the right and will take the user to the /jamf/v1/patch/ {title} endpoint to view the JSON. All GUI actions now provide feeback on success or error ( ) Organized code. JSON validation for API. Really big documentation update (now hosted on Read the Docs). Installation instructions for macos and Docker. Added GET /api/v1/backup. Download a zipped archive of all patch definitions on the server. Version history notes. Note: Removed most of the UI and some API endpoints no longer required without the associated UI views ( ) The non-existent requirements file now exists ( ) Patch eligibility criteria added to software title view ( ) Fixed UI redirects ( ) Switched to Pipenv for development ( ) 5

10 ( ) Typos and such ( ) Editing software title in the UI view ( ) Moved javascript out of the HTML and into static. Database moved to application directory. Patch title deletion. Bug fixes ( ) UI view for individual software titles ( ) Bug fix for software title creation ( ) Added RSS feed ( ) Database improvements. Proper deletion of all objects linked to a patch ( ) Initial GUI. Deduplication of criteria entries. Extension attribute objects ( ) Initial commit. 6 Chapter 1. Change History

11 CHAPTER 2 Using Patch Starter Script Patch Starter Script is a tool to enable admins to create patch title definitions and version data to use with the Patch Server API. The patchstarter.py script is available on GitHub. Refer to the readme on the project s homepage for more information on usage and options. 2.1 Create a New Title Here is a basic example of using patchstarter.py to generate a definition and then sending it to the patch server: curl \ -X POST \ -d "$(python patchstarter.py /Applications/GitHub\ Desktop.app -p "GitHub" )" \ -H 'Content-Type: application/json' 2.2 Update an Existing Title s Version Here is a basic example of using patchstarter.py to generate version data for an application and then add it to an existing title on the patch server: curl \ -X POST \ -d "$(python patchstarter.py /Applications/GitHub\ Desktop.app -p "GitHub" -- patch-only)" \ -H 'Content-Type: application/json' 7

12 8 Chapter 2. Using Patch Starter Script

13 CHAPTER 3 Troubleshooting If you encounter issues between Jamf Pro and your Patch Server you can investigate using the resources detailed here. 3.1 Jamf Pro s Connection Test Jamf Pro has a test option to verify it can contact the Patch Server and read software titles. In Jamf Pro, go to Settings > Computer Management > Patch Management > <Your Patch Server> in the management console. Click the Test button at the bottom of the page. 9

14 3.2 Jamf Pro Logs If you enable DEBUG mode for Jamf Pro logging, you can search for entries with SoftwareTitleMonitor. The debug statements will show when the sync occurs, what titles are being requested, and the error encountered. 10 Chapter 3. Troubleshooting

15 CHAPTER 4 Testing the Patch Server Warning: Using the included run.py script is not recommended for a production environment. See the other options below depending upon your platform. Clone the project repository to the system that will run the application. Change into the directory for the project, create a Python virtual environment, and install the project requirements to it. $ cd /path/to/patchserver $ virtualenv./venv $ source./venv/bin/activate (venv) $ pip install -r./requirements.txt Run the application. python run.py You will be able to access the application using localhost or your computer s IP address at port

16 12 Chapter 4. Testing the Patch Server

17 CHAPTER 5 Running as a Docker Container In the installation/docker/ directory of the project repository is a Dockerfile that can be used to launch the patch server as a container. Clone the project repository to your computer. Create the Docker image with: $ cd /path/to/patchserver $ docker build --tag patchserver:latest -f installation/docker/dockerfile. If you have Docker installed, you can run the image with: $ docker run -v /<patchserver-data>:/var/lib/patchserver -p 5000:5000 patchserver Note: Use the -d option to run the container in the background. Note: The -v /<patchserver-data>:/var/lib/patchserver option is to mount a local directory to the path in the running container where the persistent data for the patch server is stored (i.e. the database). Warning: If you do not attach a volume to /var/lib/patchserver the database will be erased when the container is stopped and removed. You will be able to access the application using the IP address of the host (your computer s IP address when running Docker locally) at port

18 14 Chapter 5. Running as a Docker Container

19 CHAPTER 6 Installation on macos The following instructions are for setting up the patch server application on a macos system using mod_wsgi-express. Warning: These instructions do not cover securing your patch server with a TLS certificate for HTTPS connections. Note: You will need to have the pip and virtualenv commands installed to follow these instructions. $ sudo easy_install pip $ sudo pip install virtualenv Note: You will need the full Xcode application on the host Mac in order to install mod_wsgi. You can download Xcode from the Mac App Store. Clone the project repository to a temporary directory. cd into the installation/macos directory. git clone /tmp/patchserver cd /tmp/patchserver/installation/macos Run the quick_install.sh. Once the script has successfully completed, you will be able to access the application using localhost or the system s IP address at port Note: The LaunchDaemon provided will start the patch server on boot. 15

20 6.1 Contents of quick_install.sh #!/usr/bin/env bash echo "Checking prerequisites..." if [[! -e /Applications/Xcode.app ]]; then echo "Xcode.app is required to install Patch Server" exit 1 fi if [[ -z $(which pip) ]]; then echo "'pip' not found, installing..." /usr/bin/easy_install pip fi if [[ -z $(pip freeze grep virtualenv) ]]; then echo "'virtualenv' not found, installing..." pip install virtualenv fi APP_DIR=/Library/PatchServer echo "Creating application directory at ${APP_DIR}" mkdir ${APP_DIR} virtualenv ${APP_DIR}/venv echo "Installing required packages..." cp../../requirements.txt ${APP_DIR} ${APP_DIR}/venv/bin/pip install mod_wsgi -r ${APP_DIR}/requirements.txt echo "Copying application files and setting permissions..." cp -r../../patchserver ${APP_DIR} cp./patch_server.wsgi ${APP_DIR} chmod 755 ${APP_DIR}/patch_server.wsgi chown -R _www:_www ${APP_DIR} echo "Creating Apache scripts in '/usr/local/bin/patchserver'..." ${APP_DIR}/venv/bin/mod_wsgi-express \ setup-server ${APP_DIR}/patch_server.wsgi \ --port=5000 \ --user _www \ --group _www \ --working-directory ${APP_DIR} \ --server-root=/usr/local/bin/patchserver echo "Copying LaunchDaemon..." cp./com.patchserver.daemon.plist /Library/LaunchDaemons/ chown root:wheel /Library/LaunchDaemons/com.patchserver.daemon.plist chmod 644 /Library/LaunchDaemons/com.patchserver.daemon.plist echo "Starting the Patch Server..." /usr/local/bin/patchserver/apachectl start echo "Quick install finished" 16 Chapter 6. Installation on macos

21 6.2 Managing the Apache Server Start the server: $ sudo /usr/local/bin/patchserver/apachectl start Stop the server: $ sudo /usr/local/bin/patchserver/apachectl stop If the server does not start, check the /usr/local/bin/patchserver/error_log file for error messages Managing the Apache Server 17

22 18 Chapter 6. Installation on macos

23 CHAPTER 7 Installation on Ubuntu Server (16.04) The following instructions are for setting up the patch server application on an Ubuntu system using gunicorn and systemd. Warning: These instructions do not cover securing your patch server with a TLS certificate for HTTPS connections. Install git, python, and virtualenv on the system: sudo /usr/bin/apt-get update -q sudo /usr/bin/apt-get install -qqy git virtualenv python-minimal Clone the project repository to a temporary directory. cd into the installation/ubuntu directory. /usr/bin/git clone /tmp/patchserver cd /tmp/patchserver/installation/ubuntu Run the quick_install.sh. sudo bash quick_install.sh Once the script has completed you should be able to access the application using the IP address of the system at port Contents of quick_install.sh #!/usr/bin/env bash function bailout() { echo "${1}: Exiting" exit $2 19

24 } # Create application directory /bin/mkdir /opt/patchserver bailout "Unable to create /opt/patchserver" 1 # Move required application files /bin/cp -r../../{requirements.txt,patchserver} /opt/patchserver /bin/cp./{config.py,wsgi.py} /opt/patchserver /bin/chown -R www-data:www-data /opt/patchserver /bin/cp./patchserver.service /etc/systemd/system bailout "Unable to copy patchserver.service" 2 /bin/chown root:root /etc/systemd/system/patchserver.service /bin/chmod 644 /etc/systemd/system/patchserver.service # Create application virtual environment /usr/bin/virtualenv -p python2.7 -q /usr/local/patchserver-venv bailout "Unable to create virtual environment" 3 # Install Python dependencies /usr/local/patchserver-venv/bin/pip install futures gunicorn -r /opt/patchserver/ requirements.txt # Enable and start the service /bin/systemctl enable patchserver.service /bin/systemctl start patchserver.service # Verify the service has started /bin/systemctl status patchserver.service 7.2 Use Nginx as a Reverse Proxy Note: Running the patch server behind Nginx will allow you to configure the web server for HTTPS. To configure TLS, refer to the Nginx documentation available here. Install Nginx on the system: sudo /usr/bin/apt-get update -q sudo /usr/bin/apt-get install -qqy nginx Remove the default Nginx site: sudo rm /etc/nginx/sites-enabled/default Modify the bind value of /opt/patchserver/config.py to have gunicorn bind the application to localhost at port 5000: bind = " :5000" Write the following to a new file called /etc/nginx/conf.d/patchserver.conf: 20 Chapter 7. Installation on Ubuntu Server (16.04)

25 Note: This file can be found in the repository at installation/ubuntu/ upstream app_servers { server :5000; } server { listen 80; server_name patchserver; } location / { proxy_pass } Restart nginx for the changes to take effect: sudo service nginx restart You should now be able to access the application using the IP address of the system at port 80 (this is the default HTTP port and you do not need to include it with the URL) Use Nginx as a Reverse Proxy 21

26 22 Chapter 7. Installation on Ubuntu Server (16.04)

27 CHAPTER 8 Add Your Patch Server to Jamf Pro Configure the patch server as an External Patch Source in Jamf Pro. Note: External Patch Sources is a feature of Jamf Pro v To add your Patch Server as a Patch External Source in Jamf Pro, go to Settings > Computer Management > Patch Management in the management console. 23

28 Click the + New button next to Patch External Source. On the next screen assign a name to your Patch Server. In the SERVER field enter the URL without with the schema or port and append /jamf/v1: <server-ip-or-hostname>/jamf/v1 In the PORT field enter 5000 (or alternatively, the the port you configured during setup). Note: Only check the Use SSL box if you have configured a TLS certificate and are serving traffic over HTTPS from your Patch Server. If you are using HTTP leave this box unchecked. 24 Chapter 8. Add Your Patch Server to Jamf Pro

29 After saving your settings, a Test button will be available on the Patch Server s page. Click it to verify Jamf Pro can connect to your Patch Server and data is being received. 25

30 Your Patch Server will now be displayed on the Patch Management settings page. 26 Chapter 8. Add Your Patch Server to Jamf Pro

31 You will now be able to add your software titles on your Patch Server from the Computers > Patch Management > Software Titles list. 27

32 28 Chapter 8. Add Your Patch Server to Jamf Pro

33 CHAPTER 9 API Authentication You may optionally generate an API token that will be required for all requests made to the following /api/v1/ title* endpoints to prevent unauthenticated requests to create, update, or delete software titles. Note: The /jamf/v1 and /api/v1/backup endpoints remain open and will not use the API token for authentication. Warning: THe UI does not yet support API authentication. You will receive a Unauthorized: Authentication required message if you attempt to use the New Title + or X (delete) options. See the Patch Server API documentation for how to create an API token. 9.1 Authenticating Requests If you have created an API token, you must include it with your requests in the Authorization header and the Bearer type: Authorization: Bearer 94631ec5c65e4dd19fb81479abdd2929 Requests without this header will be rejected with a 401 status. 9.2 Retrieve/Reset the API Token In the event you lose your API token, you can use a command line utillity such as sqlite3 to retrieve the existing token: 29

34 $ sqlite3 patch_server.db "SELECT * FROM api_token;" If you wish to reset the token, write a stub file into the patchserver application directory named reset_api_token and restart the server. The API token will be deleted from the database and the stub file cleared. You will then be allowed to create a new API token using /api/v1/token. 30 Chapter 9. API Authentication

35 CHAPTER 10 Patch Server API Note: To retrieve the JSON of a patch definition on the server, refer to the Jamf Pro Patch API documentation Endpoints Resource Operation Description Backup GET /api/v1/backup Downloadable archive of all software titles. Software Title POST /api/v1/title Create a patch definition. POST /api/v1/title/(name_id)/version Create a patch version. DELETE /api/v1/title/(name_id) Delete a patch definition. Token POST /api/v1/token Create the API token. Webhooks DELETE /api/v1/webhooks/(webhook_id) Delete a webhook Reference GET /api/v1/backup Download a zipped archive of all patch definitions. Example Request: GET /api/v1/backup HTTP/1.1 Example Response: A successful response will return a 200 status and a zipped archive containing the patch definitions. 31

36 HTTP/ OK Content-Type: application/zip <patch_archive.zip> POST /api/v1/token Create an API token for the server. Example Request: POST /api/v1/token HTTP/1.1 Example Response: A successful response will return a 201 status with the API token. HTTP/ Created Content-Type: application/json { } "token_created": "94631ec5c65e4dd19fb81479abdd2929" Error Responses A 403 status is returned if an API token already exists. HTTP/ Forbidden Content-Type: application/json { } "forbidden": "A token already exists for this server" Return POST /api/v1/title Create a new patch definition on the server. Example Request: POST /api/v1/title HTTP/1.1 Content-Type: application/json { } "id": "Composer", "name": "Composer", "publisher": "Jamf", "appname": "Composer.app", "bundleid": "com.jamfsoftware.composer", "requirements": ["requirementobjects"], "patches": ["versionobjects"], "extensionattributes": ["extensionattributeobjects"] Note: The JSON schema for a patch definition can be found in the project repository at: patchserver/ 32 Chapter 10. Patch Server API

37 routes/validator/schema_full_definition.json Example Response: A successful response will return a 201 status with the numerical database ID as well as the definition s ID. HTTP/ Created Content-Type: application/json { } "database_id": 1, "id": "Composer" Error Responses A 409 status is returned if you attempt to create a patch definition using an ID that already exists in the database. HTTP/ Conflict Content-Type: application/json { } "database_conflict": "A software title of the provided name already exists." A 400 status can be returned if your patch definition fails a validation check against the JSON schema. If this occurs, a reason will be provided in the JSON response. HTTP/ Bad Request Content-Type: application/json { "invalid_json": "Validation error encountered with submitted JSON for item: /u 'true' is not of type u'boolean'" } A 400 status can be returned if your patch definition fails a validation check against the JSON schema. If this occurs, a reason will be provided in the JSON response. HTTP/ Bad Request Content-Type: application/json { "invalid_json": "Validation error encountered with submitted JSON: u'true' is not of type u'boolean' for item: /patches/0/components/0/criteria/0/and" } POST /api/v1/title/(name_id)/version Create a new patch version for an existing patch definition. Example Request: POST /api/v1/title/composer/version HTTP/1.1 Content-Type: application/json { "version": "10.1.1", "releasedate": " T10:08:38.270Z", "standalone": true, Reference 33

38 } "minimumoperatingsystem": "10.9", "reboot": false, "killapps": [ { "bundleid": "com.jamfsoftware.composer", "appname": "Composer.app" } ], "components": [ { "name": "Composer", "version": "10.1.1", "criteria": ["requirementsobjects"] } ], "capabilities": ["requirementsobjects"], "dependencies": [] Note: The JSON schema for a patch definition can be found in the project repository at: patchserver/ routes/validator/schema_version.json Example Response: A successful response will return a 201 status. HTTP/ Created Content-Type: application/json {} Error Responses A 400 status can be returned if your patch version fails a validation check against the JSON schema. If this occurs, a reason will be provided in the JSON response. HTTP/ Bad Request Content-Type: application/json { "invalid_json": "Validation error encountered with submitted JSON: u'true' is not of type u'boolean' for item: /patches/0/components/0/criteria/0/and" } DELETE /api/v1/webhooks/(webhook_id) Delete a configured webhook from the server by ID. Example Request: DELETE /api/v1/webhooks/1 HTTP/1.1 Example Response: A successful response will return a 204 status. HTTP/ No Content 34 Chapter 10. Patch Server API

39 Error Responses A 404 status is returned if the specified webhook does not exist. HTTP/ Not Found Content-Type: application/json { } "webhook_id_not_found": 1 DELETE /api/v1/title/(name_id) Delete a patch definition on the server. Example Request: DELETE /api/v1/title/composer HTTP/1.1 Example Response: A successful response will return a 204 status. HTTP/ No Content Error Responses A 404 status is returned if the specified patch definition does not exist. HTTP/ Not Found Content-Type: application/json { } "title_not_found": "Composer" Reference 35

40 36 Chapter 10. Patch Server API

41 CHAPTER 11 Jamf Pro Patch API 11.1 Endpoints Resource Operation Description Software Title GET /jamf/v1/software List all software titles. GET /jamf/v1/software/(name_ids) List selected software titles. GET /jamf/v1/patch/(name_id) Return a patch definition Reference GET /jamf/v1/software Returns all available software titles on server. Example Request: GET /jamf/v1/software HTTP/1.1 Accept: application/json Example Response: A successful response will return a 200 status and an array of software title summaries. HTTP/ OK Content-Type: application/json [ { "currentversion": "10.1.1", "id": "Composer", "lastmodified": " T17:39:58Z", "name": "Composer", "publisher": "Jamf" 37

42 ] }, { }, { }, { } "currentversion": "10.1.1", "id": "JamfAdmin", "lastmodified": " T17:39:51Z", "name": "Jamf Admin", "publisher": "Jamf" "currentversion": "10.1.1", "id": "JamfImaging", "lastmodified": " T17:39:53Z", "name": "Jamf Imaging", "publisher": "Jamf" "currentversion": "10.1.1", "id": "JamfRemote", "lastmodified": " T17:39:56Z", "name": "Jamf Remote", "publisher": "Jamf" GET /jamf/v1/software/(name_ids) Returns a selection of software titles on server. The software title IDs must be passed as a comma separated string. Example Request: GET /jamf/v1/software/composer,jamfimaging HTTP/1.1 Accept: application/json Example Response: A successful response will return a 200 status and an array of software title summaries. HTTP/ OK Content-Type: application/json [ ] { }, { } "currentversion": "10.1.1", "id": "Composer", "lastmodified": " T17:39:58Z", "name": "Composer", "publisher": "Jamf" "currentversion": "10.1.1", "id": "JamfImaging", "lastmodified": " T17:39:53Z", "name": "Jamf Imaging", "publisher": "Jamf" Error Responses 38 Chapter 11. Jamf Pro Patch API

43 GET /jamf/v1/software/composers,jamfimager HTTP/1.1 Accept: application/json A 404 status is returned if any of the specified software titles do not exist. HTTP/ Not Found Content-Type: application/json { } "title_not_found": [ "Composers", "JamfImager" ] GET /jamf/v1/patch/(name_id) Returns a selection of software titles on server. The software title IDs must be passed as a comma separated string. Example Request: GET /jamf/v1/patch/composer HTTP/1.1 Accept: application/json Example Response: A successful response will return a 200 status and the full patch definition for the specified software title. HTTP/ OK Content-Type: application/json { } "id": "Composer", "name": "Composer", "publisher": "Jamf", "appname": "Composer.app", "bundleid": "com.jamfsoftware.composer", "requirements": ["requirementobjects"], "patches": ["versionobjects"], "extensionattributes": ["extensionattributeobjects"] Error Responses GET /jamf/v1/software/composers HTTP/1.1 Accept: application/json A 404 status is returned if any of the specified software title does not exist. HTTP/ Not Found Content-Type: application/json { } "title_not_found": "Composers" Reference 39

44 40 Chapter 11. Jamf Pro Patch API

45 CHAPTER 12 User Interface In a browser, the root of the patch server will take you to the main page where you can view and manage the available 41

46 software titles Upload a New Software Title Click the New Title button to bring up the file selector. Browse for the JSON file of the patch definition and then click Upload. You will recieve a confirmation of a successful upload Upload Errors If the patch server rejects your upload of a patch definition, it will provide a notification with the reason so you can correct the cause and retry. There is a conflict with an existing software title. 42 Chapter 12. User Interface

47 The patch definition failed validation, but the cause is displayed Update a Title s Version Click the green Up icon for a title to display a file prompt. Select the JSON file containing the new version data and submit it. You will receive a confirmation of a successful upload Update a Title s Version 43

48 You will also receive similar feedback for errors as with creating new titles Other Title Actions There are additional actions available for each software title. The blue View icon will take you to the URL of the patch definition JSON. The red X icon will delete the title from the server. Warning: The delete action cannot be undone Backup Patch Definitions Click the Backup button and you will download a zipped archive of all patch definitions for all your software titles. Note: This is a feature of the API that you can use with automation for scheduled backups of the server. 44 Chapter 12. User Interface

49 12.6 Webhooks The patch server can send notifications on changes to software titles on the server to remote servers via HTTP POST. To configure a webhook, click the New Webhook button to bring up the configuration screen. Enter the remote URL and select from the available options: Enabled: Enable or disable this webhook. Verify SSL: Enable or disable SSL verification (HTTPS). Send Definition: When an event is sent, include a fully copy of the entire patch definition for the software title Webhooks 45

50 46 Chapter 12. User Interface

51 HTTP Routing Table /api GET /api/v1/backup, 31 POST /api/v1/title, 32 POST /api/v1/title/(name_id)/version, 33 POST /api/v1/token, 32 DELETE /api/v1/title/(name_id), 35 DELETE /api/v1/webhooks/(webhook_id), 34 /jamf GET /jamf/v1/patch/(name_id), 39 GET /jamf/v1/software, 37 GET /jamf/v1/software/(name_ids), 38 47