Welcome to JSS in a Box!
Before we go any further, here’s the link to where you can actually find the project. https://github.com/franton/JSS-In-A-Box
So what is it? Simply put it’s an Ubuntu based setup script for JAMF’s Casper Suite JSS and frankly speaking it’s about 80% of JAMF’s CJA course in one handy script.
(FYI It leaves out the Windows stuff you would do on the CJA and I’ve already tipped off the various JAMF employees I know, so they’re looking for this now! No cheating!)
So how do we start? First, open up the script with your favourite text editor. The beginning of the script will look like this:
As you can see there’s a whole bunch of variables that can be pre-configured to suit your needs. These are annotated in the script but here’s a quick guide to their use.
useract
This is used to get an admin user name. It’s used to derive a home folder location on Ubuntu server and is where JSS-in-a-Box will be looking for it’s working files.
letsencrypt
This is a boolean variable used to determine if you are going to use LetsEncrypt as your primary SSL certificate authority.
Leaving this set to FALSE means your JSS will be running on insecure port 8080 via HTTP.
Setting this to TRUE will allow JSS-in-a-Box to automatically take the following variables, grab the appropriate SSL certificates from LetsEncrypt, store them into a Java KeyStore (.jks file), appropriately configure Tomcat to use this for HTTPS traffic on port 8443.
Lastly JSS-in-a-Box will set up a recurring cron job to do certificate updates because LetsEncrypt only generates 90 day valid certificates.
ssltestmode
This is a boolean variable used to determine if LetsEncrypt is going to run off their test staging server or not.
Set this to TRUE while you are conducting any testing and this will generate an insecure key.
Setting this to FALSE will mean you will be generating proper certificates for your domain.
ssldomain
This is the FQDN for where you wish to generate your SSL certificate.
sslemail
This is the email of the administrator where the SSL certificates will be registered to that have been obtained from LetsEncrypt.
sslkeypass
This is the internal password for the Java KeyStore used by Tomcat. It’s advisable you change this from “changeit”.
mysqluser
This is the username for a MySQL root user. Only change this is you don’t call your root database user as “root”!
mysqlpw
This is the password for the root MySQL user.
mysqlserveraddress
This is the address for the MySQL database. By default, JSS-in-a-Box will create it’s databases on localhost but this can be configured to talk to an external server here.
JSS-in-a-Box automatically configures each Tomcat instance to point to a specific database server from here. It also sets up the database grants to only allow access from this specific JSS, it’s advisable you do not change this if you’re in any doubt!
dbuser
This is the username for the JSS to use accessing it’s own database. This can be changed but the default is usually fine.
dbpass
This is the password for the JSS database user above. It’s recommended this is changed from “changeit”.
It’s highly recommended that you don’t change the variables below this as it will probably break the script operation!
Assuming you have a properly configured Ubuntu server (hostname, ntp, openssh and internet accessible), then you can proceed.
scp across the jus-in-a-box.sh script and the JSS ROOT.war files to your admin user folder on the server. (See the video at the bottom of the post for an example on how to do this).
ssh into the server and check to see if both the script and the ROOT.war files are in place. If so, you’re good to start!
Run the script with sudo. JSS-in-a-Box requires root level permissions to do it’s work and will be unhappy if it’s run with standard user permissions. (It’ll ask you nicely to run as root). Once run this way, it’ll give you the following options:
Check & Install Server Software
You should run this first, for a couple important reasons. 1) It will update, install and configure all the software you need to run a JSS (tomcat, java 8, java cryptography extensions, firewall etc). 2) The options below are deactivated until you do!
This process is the lengthiest part of the procedure and depending on your network speeds and internet connection, can take a while. At home, I found this can take around 40 minutes.
Show list of current JSS instances
This will show a list of all the JSS Tomcat instances currently running on the server. On a first run, this will not report anything.
New multi context instances will show up under the name they were created under.
A single instance will be listed as ROOT.
Create new JSS & Database Instance
This will first show existing JSS instances running, then prompt you for a new instance name. It will create a new JSS instance, create a new database with appropriate grants, create new JSS log file/folder and configure everything before restarting Tomcat.
Delete existing JSS & Database Instance
This will show existing JSS instances running and then prompt you for the exact name of the instance to delete. After confirmation, it’ll stop Tomcat, drop the database and then delete the JSS instance.
I hope you have a backup of the database before you do this!
Dump MySQL Database to file
This will create a database dump of the specified JSS instance and place it in your admin’s home folder. If you’ve any DR plans for the database, this is the place to grab the files from.
NOTE: Currently there’s no time stamps on the filenames, so each new dump will overwrite the existing one. If you’ve a way of doing this, tell me how! Implementing this is not a priority for me currently.
Upload MySQL dump to database
Will drop the existing database, create a blank one and upload the dump to that database. The name of the database is parsed from the dump filename so the limitation is you can only upload the database to the instance you got it from in the first place. This limitation is deliberate.
Upgrade a single JSS instance
Before running this, please make sure you have an updated ROOT.war file ready in your admin’s home folder this will simply replace the instance like for like.
This will show existing JSS instances running and then prompt you for the exact name of the instance to upgrade.
This will then stop tomcat, delete the instance name from tomcat (while leaving the database in place) and then replace it from the ROOT.war in your admin’s home folder.
Technically speaking, this could be used to do a JSS downgrade as well as there is no version checking however this isn’t recommended as JAMF could do internal database schema changes without warning rendering the instance unusable.
Upgrade ALL JSS instances
This is the option to use if you’ve multiple JSS instances and you’re happy that an upgrade won’t break anything.
It will perform the same as the single instance upgrade but recursively though ALL existing instances. Obviously please be careful with this and I take no responsibility for it going horribly wrong!
Please make sure you have an updated ROOT.war file ready or this will simply replace the instance like for like.
Refresh SSL certificates from CA
If you have enabled the LetsEncrypt variable, the setup procedure sets up a cron job to do automatic SSL certificate replacement. However thanks to limitations with cron on Ubuntu, I cannot set the job to run at a suitable interval so instead it runs every night with the option to replace only if needed.
In case you ever need to run this manually, this option is provided to do this process manually.
It’s highly recommended that you try this script out on a non production server first to see how it behaves before going into production!
And since you’ve made it this far, try running it like this too: sudo ./jss-in-a-box.sh -h
Below you can find my demonstration video of the tool in operation. The video doesn’t run real time for all of it, but you can go from a freshly installed Ubuntu 14.04 LTS server to a hardened running JSS in under an hour.
[embedyt]https://www.youtube.com/watch?v=ZMx-Xb2a9dM[/embedyt]