From 64f2263ac367b17004748a4ca0b2db166cc2a9b1 Mon Sep 17 00:00:00 2001 From: Filipp Lepalaan Date: Thu, 22 Sep 2016 15:07:49 +0300 Subject: Added example --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 05eee34..1ba8bc6 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ### Introduction -`machammer` is library/microframework for Macintosh system administration. The idea is to provide common, often-used functions for admins to build their own management tools. +`machammer` is library/microframework for Macintosh system administration. The idea is to provide a set of common, often-used functions for admins to build their own management tools. ### System Requirements @@ -8,9 +8,58 @@ - OS X (tested with 10.11) +### Example + +In this example we will create an initial installation and setup script for a new Mac. We will install some configuration profiles and packages, copy some apps and configure our print queues. + +We will assume you have a fileshare where you also keep your installation files. In this example, the fileshare is mounted on `/Volumes/MyShare` and all the installation resources are in a subdirectory called `Installation`. + +```python +import os +from machammer import functions as mh # Import general-purpose admin commands +from machammer import printers # Import printer-related commands + +APP_ROOT = '/Volumes/MyShare/Installation' +mh.display_notification('Starting installation') + +# Configure the Mac to use our in-house software update server +mh.install_profile(os.path.join(APP_ROOT, 'Settings_for_SoftwareUpdate.mobileconfig')) + +# Install all Software Updates. This may reboot your machine (provide restart=False, if you want to avoid that) +mh.install_su() + +myprinter = ('LaserWriter 8500', 'LaserWriter8500.ppd', 'lw.example.com',) +printers.add_printer(myprinter) + +# Install Java. mount_and_install takes 2 arguments - the path to the disk image and the path to installation package on the mounted volume +mh.mount_and_install(os.path.join(APP_ROOT, 'jre-8u101-macosx-x64.dmg'), 'Java 8 Update 101.app/Contents/Resources/JavaAppletPlugin.pkg') + +# Install Microsoft Office. mount_image returns the path to the new mountpoint +p = mh.mount_image('/Volumes/MyShare/Installation/Office2016.dmg') +mh.install_package(os.path.join(p, 'Microsoft_Office_2016_15.23.0_160611_Installer.pkg')) + +# Install ArchiCAD 19 +p = mh.mount_image(os.path.join(APP_ROOT, 'ArchiCAD/19/AC19-3003-INT.dmg')) +mh.exec_jar(os.path.join(p, '/ArchiCAD Installer.app/Contents/Resources/Java/archive.jar'), 'localadmin') + +# Install Viscosity on laptops +if mh.is_laptop(): + p = mh.mount_image('/Volumes/MyShare/Installation/Viscosity 1.6.6.dmg') + mh.copy_app(os.path.join(p, 'Viscosity.app')) + +mh.display_notification('Installation complete!') +sys.exit(0) +``` + +Save that in `install.py` (or whatever you want) and just run with `sudo python install.py`. I would recommend putting the installation script alongside with machammer itself on the fileshare so you don't have to install anything on the client machine to be able to run it. + +`install.py` serves two important purposes - first and foremost, it allows you to get machines up and running quickly and with minimal user-intervention (depending on the payload). Secondly, it also serves as your official configuration documentation! + + Pro tip: put install.py under version control! + ### system_profiler -machammer includes `system_profiler` - a simple wrapper around OS X's `system_profiler (1)` tool. It provides a simple API for accessing system profile information as well as caching to improve performance (especially when dealing with application profile data). +`machammer` includes `system_profiler` - a small wrapper around OS X's `system_profiler (1)` tool. It provides a simple API for accessing system profile information as well as caching to improve performance (especially when dealing with application profile data). #### Usage @@ -27,6 +76,14 @@ print([x['version'] for x in results]) Check `tests.py` for more usage examples. +### FAQ + +* Q: Why not use Bash? +* A: It's true that most of this stuff is just glue to various command line utilities and using Bash might save some keystrokes, but Python is just a much better programming language with an actual standard library. +* Q: Why not use Munki? +* A: No reason whatsoever. Munki is great and you should totally use it, if it works for you. I just prefer to read and write code than learn a new XML syntax. For me personally, it was difficult to "start small" with Munki - there's a lot you have to learn to get started. Also, there are plenty of apps out there that don't conform to the standard PKG/app bundle format (like the ArchiCAD example above) and your best bet at tackling those is just plain-old scripting. To paraphrase Einstein - an installation tool might take you from A to B, but scripting can take you anywhere. :-) + + ### License Copyright (c) 2016 Filipp Lepalaan -- cgit v1.2.3