- Before I start,
let me acknowledge the Gadigal people
of the Eora nation
who always have and always will be
the owners of the land on which I sit,
and their elders by the past,
present, and emerging.
Hello, my name is Tony Williams,
and I'm a system engineer for Suncorp.
So what was the problem
that was worth four weeks
of spare time doing?
Well, the scripts in Jamf Pro
are not tracked,
no log of who changed what when,
not versioned, so you can't roll back,
and they're not backed up,
and editing it in the GUIs
is less than ideal.
We need a better way.
Doesn't Git2JSS solve that?
Good question.
There's actually two versions of Git2JSS.
Both assume a fair knowledge of Git
and contain a fair amount of complexity.
Neither really covers
renaming and deleting scripts.
We want something better.
So I wrote Scriptorium.
It's a Python script
that strips all the complexity away
and delivers a simple to use,
total solution for handling the scripts
in your Jamf Pro instance.
I have to admit that in early June
when I'm recording this,
it has just entered production.
And I'd really like to extend
a direct extension attribute soon.
So how does it work?
Scriptorium uses Git repositories
to provide backup and version inventory
of two directories on your computer.
When we download a script from Jamf Pro,
it stores the XML in one directory.
It extracts the actual script
from the XML
and stores it in its own directory.
After you edit scripts
in the text directory,
you perform a Scriptorium commit.
it propagates the changes through
to the XML file
and Jamf Pro
before doing a Git commit
on both directories.
You can if you wish to specify
a commit message.
A number of other Scriptorium commands
do a commit at the end of their process.
They also allow you to set
the commit message.
At this point,
we've done a commit without a push,
the changes are on our computer
and Jamf Pro,
but not yet on the Git repositories
in the cloud.
To do that, we need to perform a push
using the Scriptorium push command.
Once you've done that,
your edits are propagated
through the whole system.
And we can consider the system fully reset
and ready for more changes to our scripts.
That's the basics.
Let's look at all the commands
Scriptorium covers.
We will have a quick look
at some of the further commands
before seeing the system in action.
The simplest command
you know of is list.
It does nothing but list the scripts
around Jamf Pro instance.
Delete removes the script
from both directories in Jamf Pro.
Unless you specify no commit,
it will also do a commit
in both directories.
The down command
downloads the scripts from Jamf Pro,
overriding any changes.
If you don't want changes overwritten
and only bring down new scripts,
you can specify no force
and changes will be left in place.
You can also specify
a single script to download
if you only want the one.
It will do a commit unless
you specify no commit.
Git does what you might expect.
It runs the git command you specify
in both directories.
This is really here
to make the task easier
and to remove a source of errors
in the system.
It quite deliberately doesn't do a commit
on anything else,
just the command you specify.
Rename changes the name of a script
in both directories in Jamf Pro.
It also does a commit
unless you don't want to.
Up is the command that detects changes
to the scripts in the text directory
and copies them into the XML
and up to Jamf Pro,
hence the name.
Because up uses git dif
to find changed files,
if you do a commit before you do up,
you'll lose track of your changes.
For this reason,
up is automatically run before any commit.
Verify allows you to check
the stated system.
It has several modes.
If you specify quit,
it will only compare the list of scripts
in each directory and Jamf Pro.
If you don't specify anything,
it will compare the text in each location
and tell you if they're identical or vary.
If you specified dif,
it will you give you a dif
between the two different texts.
This is gonna get long quite quickly,
so if you only wanna check one script,
perhaps before you do some edits,
you can specify your script to check.
The final command to look at is add.
You can see it has a fair degree
of complexity with a lot of options.
It's this complex
so you can specify most of the metadata
for a script on the command line.
Anything you don't specify
in the command line,
Scriptorium will prompt you for.
After, before, and reboot
are a mutually exclusive group,
so Scriptorium will complain
if you try to use more than one of them
on the command line.
If you don't specify zero parameters
for your script,
Scriptorium will ask you
for the fourth parameters.
If you're under a blank parameter,
it will stop asking.
Let's start our look at Scriptorium
in action with that.
Here's our command.
I specify don't commit
so it can make some changes
before we commit the new script.
Hit enter
and we get asked for the file name.
Enter the file name.
Hit return
and you get asked for the notes.
Enter a note.
Here we are asked
for the fourth parameter.
Remember, Jamf Pro
supplies the first three
when it runs the script.
So we enter one...
And another...
Then we enter a blank.
Scriptorium sees the blank parameter
and doesn't ask for any more
before it asks for a category
for the script.
The list is created on the fly
for any actual categories
you have in Jamf Pro.
In my test instance, I only have two.
So hit return to select developer.
The next is to select between
the three possible priorities.
I select the four with the down arrow--
notice the highlighting
has moved down a line--
then hit return,
at which point Scriptorium
has all it needs
and creates the script, the XML file,
and the Jamf Pro record.
Notice the ?1.
This is the Git addon to ZSH
telling me that I now have one file
that has not been committed to Git
or pushed to our repo.
This concludes why
it's best to run Scriptorium
in the text directory
rather than the XML directory
or a random one.
This is the view from vest code.
Notice the blue 1
telling us we have a file loose
down in our Git repo.
Also notice on the righthand
that the text in the script
has been set for commit
containing the name of the script.
It's ready there for us to start
entering the actual script.
Now let's do our commit,
and this time we will specify a message.
And Scriptorium does the commit twice,
once in each directory.
The shell prompt now changes
to up arrow 1,
which tells us we no longer have
any uncommitted files,
but we have commit not pushed
to a cloud repository.
So now do a push.
Remember, this could have been specified
at the commit stage
or the commit and push
both done with the add command.
And here is the output.
Once again,
you can see the result
of two git commands,
and notice how the prompt
is now free of git info.
Let's have a look at some verify commands.
Here we see a quicky verify.
It does an LS in each directory
and grabs the script list
from the JP server
and compares them all.
A straight verify does the same
as the quick
and then compares each script.
It prints an asterisk
to every script it compares.
That's pretty lame
without any differences to find,
so let's add a line to our script
and propagate that through the system.
And now we will change
"What a silly script."
So now we do a...
verify with dif.
Once again, the prompt tells us
we have changed the file.
The verify does the list compare,
and they are the same.
But halfway through
looking at all the scripts,
it finds a difference.
At the top is the contents
of the text file
and at the bottom
that of the XML file.
Let's specify a single script
and see the difference.
You can see the same dif
but only a single asterisk
as we only process one script.
Notice that we also gave confirmation
that the XML file matches the contents
of our Jamf Pro server.
Let us do a commit with a push.
Remember that we'll do an up
taking the contents of any changed files
in the text directory,
in our case just JNUC demo.sh,
and insert them in the XML file
and up to Jamf.
And we had a large chunk of output
from the git
before a prompt with no git info.
If we now do the same verify
of a single script,
you can see it is the same
in all three places.
"So what about somebody else
editing a script?" I hear you ask.
Good question.
Let's give it a go.
So let's go to the Jamf GUI
and change "silly"...
Back to "useless."
Do a verify to see what's what.
And we're told that the XML file
does not match the Jamf server.
Let's get more specific
and look closer
so that we are using -d,
instead of --dif.
All Scriptorium options can be specified
with their first letter in this way.
And look at that.
The script text is the same as the XML,
it is the Jamf server that's different,
as we know.
After all we changed it.
So what to do?
The single source of truth
is always the Jamf server.
After all, it doesn't matter
what we have on our computer
or in our git repositories.
It's the script in Jamf Pro
that's run on our Mac fleet.
Because of that,
if we get a difference
between the server and us,
it's us is who is wrong.
So we fix it by bringing down
the script from the Jamf server.
And that will look like this.
Notice the prompt is changed again.
We are out of sync with our local repo.
So we better fix that.
A commit and a push
will do what is needed.
Right at the top line,
"Processing JNUC demo.sh,"
is Scriptorium doing up.
In this instance,
it's not necessary,
but it happens automatically.
Then below you can see the two commits
with the commit message
set to the file name,
then finally, the two pushes.
When that completes,
our prompt is back to telling us
all is good.
Before I go,
let's see what a git log command gives us.
Well, as you can see,
Tony Williams has been
committing a lot of changes
to one file, JNUC demo.sh.
What happens if we edit
multiple scripts?
Here the prompt is telling us
three files have been modified.
And a git status should tell us some more.
It lists our three modified files.
And commit and push
should get them changed across the system.
At the top, you can see up
processing the three files
before the familiar output
of commit and push.
Once again, notice the prompt is green.
So what does a git log command
reveal this time?
At the top,
you can see that because
we didn't specify a commit message,
Scriptorium lists the three files
that were changed.
Probably what we would've done ourselves.
The git log is tracking all our changes
telling us which scripts get changed
and by whom.
Before we go,
we should have a quick look
at Scriptorium's help system.
Scriptorium -h will get us...
A list of all the commands.
We can also put -h
for help after a command.
For a good summary
of the command's parameters,
look in the usage section
right at the top,
and you can see how it specifies
the mutually exclusive group -b, -a, -r
by surrounding them with brackets
and putting a pipe between
the three alternatives.
What happens if we try and use
two of the options?
We get gently scolded
with command usage again
and a more explicit error message.
You can also see
with the red arrow up right
that we return an error.
If you had better eyes than me,
you can see that the error code is two.
So we come to the end
of my presentation.
Here is where you can find
both Scriptorium
and me online.
So a big thank you
to Jamf for organizing JNUC2021
and a big thank you to you for listening.
Enjoy the rest of your conference.