README

• GSX module
  • Remarks
  • Configuration
  • Making the certbundle.pem
  • Populating GSX Information

Updates warranty status from Apple, designed as a warranty module supplement.

The GSX table provides the following information:

• Warranty status
• Coverage end date
• Coverage start date
• Days of coverage remaining, as last pulled from GSX
• Estimated purchase date
• Country of purchase
• Registration date
• Product decryption
• Shipping configuration
• Contract coverage end date
• Contract coverage start date
• Warranty contract type
• Labor covered
• Parts covered
• Warranty Service Level Agreement
• Is Mac a GSX loaner Mac
• Human readable warranty status
• Is vintage Mac
• Is obsolete Mac

The GSX module also updates the warranty and machine tables with the following:

• Purchase date
• Warranty end date
• Warranty status
• Product description

Data can be viewed under the GSX tab on the client details page or using the GSX listings view

Remarks

• Requires the SOAP extension installed in php http://php.net/manual/en/book.soap.php
• The client triggers the server to do a lookup once a day
• Obsolete Macs are not available from Apple and are instead processed using the warranty module's back end
• Previously it was recommended to only enable the GSX or the Warranty module, this has changed with MunkiReport 2.14 and the GSX module requires the Warranty module to be enabled

Configuration

Before you use the GSX module, you need to configure the .env file with your GSX account information. Some variables are not required.

GSX_ENABLE=true
GSX_CERT='/path/to/certbundle.pem'
GSX_CERT_KEYPASS='pass'
GSX_SOLD_TO='00000xxxxx'
GSX_SHIP_TO='00000xxxxx'
GSX_USERNAME='gsx_user@domain.com'
GSX_DATE_FORMAT='m/d/y'

Making the certbundle.pem

These steps assume you've created your SSL certificates using https://www.watchmanmonitoring.com/generating-ssl-certificates-to-meet-applecares-august-2015-requirements/

When creating the certbundle.pem, you must have the six signed pems sent back from Apple as well as the four gsx-* files generated by you that you sent to Apple. First put all 10 files into a folder. Let's call it GSX-Certs.

Within the GSX-Certs folder, you need to cat your gsx-production.key and the Applecare-XXXX-Prod.apple.com.chain.pem together to form the bundle. In Terminal, cd to the GSX-Certs folder. Then run "cat Applecare-APP1234-0000123456.Prod.apple.com.chain.pem gsx-production.key > certbundle.pem" making sure to put your AppleCare and sold to number in place of the example numbers.

This will output a certbundle.pem file that is roughly 6.1KB in size. Treat this file and the rest of the GSX certificates as passwords. Protect them. All that's left is to make sure that the certbundle.pem contains the proper data, example below, and point MunkiReport to where it's stored in a web server readable place in the config.php with the gsx_cert parameter.

Additional material can be found at https://github.com/filipp/gsxlib#q-how-do-i-create-the-necessary-pem-file

Example certbundle.pem:

-----BEGIN CERTIFICATE-----
BLASOQ()*Q#()**)REW)*(EW*)*E)WUR)*EW(UR)
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
0990320003q43090435J403439590S-S=DS=-
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
)_#_)#)$IK_#@))KDE_)FD_SF)DSF_DS)FDS_FDSFSD
....
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
Proc-Type: ....
DEK-Info: ...
BUNCH OF GIBBERISH
-----END RSA PRIVATE KEY-----

Populating GSX Information

Once you've configured the GSX module you'll probably want to recheck all of your existing warranty data against Apple's API. For an individual machine, that's easy - just go to Clients > Computer Name > Show (menu in the upper-left corner) > GSX > Recheck Warranty Status. For an entire fleet, that's a fair amount of work. Let's automate this.

First, open MunkiReport, then click Listings > GSX. In the upper-left corner of the page, click the pop-up menu, then click All to display all of your Macs. In the upper-right corner of the page, click CSV. Select everything on the page, copy it to the clipboard, and paste it into a new document in your favorite text editor (TextWrangler is free, just don't use TextEdit). Save it to your Desktop as all-macs.csv.

Next, we'll want to trim this down to just serial numbers. Open the Terminal, then paste this:

cd ~/Desktop && awk -F "\"*,\"*" '{print $2}' all-macs.csv > serials.txt`

Hit enter, and you should see a new text file appear on the Desktop, called serials.txt. Open that up in your text editor, and delete the first line (called Serial Number). Save and close.

Now, make a new document in your text editor, and call it gsx_lookup_all.sh, also saving it to your Desktop. Paste this:

#!/bin/bash

MR_BASE_URL='https://yourmunkireportserver/index.php?'
MR_LOGIN='datauser'
MR_PASSWORD='secretpassword'
COOKIE_JAR=$(curl -s --cookie-jar - --data "login=${MR_LOGIN}&password=${MR_PASSWORD}" ${MR_BASE_URL}/auth/login)
SESSION_COOKIE=$(echo $COOKIE_JAR | sed 's/.*PHPSESSID /PHPSESSID=/')

while read serial
do
   curl -s --cookie "$SESSION_COOKIE" ${MR_BASE_URL}/module/gsx/recheck_gsx/"$serial" >> gsx_lookup.log
done < serials.txt

exit 0

Be sure to edit MR_BASE_URL, MR_LOGIN, and MR_PASSWORD for your server information.

Open the Terminal, then paste the following:

chmod +x ~/Desktop/gsx_lookup_all.sh

Hit enter to make the script executable. Then, finally, run the script:

~/Desktop/gsx_lookup_all.sh

Although it won't output anything to the Terminal, you can follow along in the log file, gsx_lookup.log.

After it's all done, you'll want to go back to MunkiReport > Listings > GSX and manually Recheck Warranty Status for any Macs that had errors.