-
Notifications
You must be signed in to change notification settings - Fork 12
Admin
- d3admin
- Adding packages
- Editing packages
- Making packages live
- Deleting packages
- Searching for packages
- Client reports
- Environment
d3admin is a command-line tool for working with packages in d3. Admins who maintain d3 packages will use it to add, edit, and delete packages, make them live, search for them on the server, and get reports about receipts on client computers.
d3admin cannot be run as root, since it needs to know who's doing things to the packages on the server. Also, the authentication credentials for write-access need to be stored in a secure location - your keychain.
The first time you run d3admin, it will go through its configuration steps, asking you for host and authentication info for the JSS API, the JSS's MySQL server, and the read-write password for the Master Distribution Point. It will store this data in your keychain, so you won't need to enter it every time you use d3admin. If you ever need to update this data, just use d3admin config.
The format for a d3admin command-line is d3admin action target(s) [options]
The actions are: add, edit, live, delete, info, search, report, config, and help
All actions can be specified with just the first letter, and most options have both a long (--walkthru) and short (-w) version. See the d3admin extended help output (-H, --extended-help) for a summary of all the actions and options. The condensed help is viewed with the 'help' action, -h, or --help
There are two modes for using d3admin: walkthru and command-line:
When the --walkthru option is is given, d3admin will prompt for a basename, edition or other data as needed. If using walkthru for adding or editing a package, it will present a menu of choices for setting the attributes of the package, warning you if invalid data is given. When you're ready to save your changes, you'll be asked for confirmation.
For example d3admin add transmogrifier --walkthru will present a menu of choices for adding a new pilot package to d3 with the basename 'transmogrifier'. d3admin edit -w will prompt for a basename or edition before displaying the menu.
This mode is the easiest to use when manually adding or editing packages.
Every attribute of a package, and other data needed for using d3admin, can be provided via command-line options. When adding a package without the --walkthru option, required attributes must be provided via options, or an error occurs. Non-required attributes will use default values, or, if you're adding a package, inherit them from the previous edition of the same basename.
The command:
d3admin add transmogrifier -g test-macs -e /tmp/test-preinstall
will add a new package for the basename 'transmogrifier'. It assumes there is a previous edition of transmogrifier, and the new one will have the same version, and the revision will be incremented by one.
The package will auto-install on machines in the computer group 'test-macs' and the script located at /tmp/test-preinstall will be added to Casper and used as the d3 pre-install script.
All other attributes of the package will be inherited from the previous edition.
If there is no previous edition, the version must be provided with -v, and the revision will be 1. All other attributes will have default values.
d3admin edit transmogrifier-2.5-2 -G 'special-macs,other-macs' -e 324
This command will change the excluded-groups for the package with edition transmogrifier-2.5-2 to 'special-macs' and 'other-macs', and will set the pre-install script to the JSS Script with id 324.
This mode is designed for automated package manipulation. Usually it's used as a step at the end of a build process, as from XCode.
Adding packages to d3 is done with
d3admin add <basename> <options>.
Using the --walkthru option will present a menu with which you can define all aspects of the package. Without --walkthru, a version, and source-path must be provided with --version and --souce-path. All other options will use default values if omitted.
The source path is a locally accessible path to one of:
- a .pkg installer, from any source
- a Casper .dmg installer, usually from Composer.app
- a 'root' folder representing the root of the target computer where the install will happen.
When given a .pkg or a .dmg, d3admin acts like Casper Admin.app in that it will add the package to Casper (and d3) and upload it to the master distribution point.
When given a path to a root folder, d3admin will use it to build a simple .pkg installer, or if --dmg is given, a Casper .dmg installer. In this sense, it's like a simplified version of Composer.app, combined with Casper Admin.app. If you need to build complex .pkgs with internal scripts and other settings, you should use Composer.app, or some other tool, first, and then add the .pkg with d3admin.
When building packages itself, the workspace folder you chose during d3admin config will be used to build the .pkg or .dmg. The --workspace option can be used to specify a different folder for this run.
See the d3admin extended help output for descriptions of all the command-line options. See Packages for descriptions of the d3-specific package attributes.
The --import option, with 'add', will import an existing Casper package into d3. The name or JSS id of the package must be given with --import:
d3admin add bingbong --import bingbong.pkg -v 1.2 -r 1 -w
Imports the existing Casper package 'bingbong.pkg' into d3 with version 1.2 and revision 1. It presents the walk-thru menu for setting other attribtutes of the package.
As with regular additions, a basename must be given as a target, and --version and --revision will be needed. Other values will be default if you don't provide them with on the command-line or with --walkthru.
Packages in d3 can be edited with
d3admin edit <basename or edition> <options>
Using the --walkthru option will present a menu with which you can edit all aspects of the package.
Without --walkthru, any options specified on the command line will be changed, others will be untouched.
See the d3admin extended help output for descriptions of all the command-line options. See Packages for descriptions of the d3-specific package attributes.
All newly-added packages have the status 'pilot' and must be made 'live' (released) to be generally available in d3.
The command d3admin live <edition> will make the edition live.
Doing this will affect the statuses of other packages with the same basename:
- The package that was previously live will become deprecated
- Any pilot packages between the previously live one and this one will become skipped
- Any newer packages than this one will remain pilots
"newer" and "older" depend on when the package was added to d3.
If you make a skipped or deprecated package live, d3admin will give you a warning when asking for confirmation:
WARNING: You're rolling back to an older edition!
ALL non-frozen installs of '<basename>' will be downgraded to this edition!
If you procede, then at the next sync, all computers with any (non-frozen) edition of the basename installed will get the older edition. Newer editions on the server, including the previously live one, will become pilots again.
This feature of d3 is enabled with the 'admin_auto_clean' value of the d3.conf file. When enabled, and a package becomes live:
- Some or all older pilot & skipped packages with the same basename are deleted from d3
- Some or all older deprecated packages are also deleted.
The 'admin_auto_clean_keep_deprecated' setting of the d3.conf file indicates how many deprecated packages to keep on the server. If auto-clean is turned on, and admin_auto_clean_keep_deprecated is 3, then at any time there will be no skipped, and 3 deprecated packages in any basename, and when the next edition is made live, the oldest deprecated edition will be deleted.
If 'admin_auto_clean_keep_deprecated' is greater than zero, and you set 'admin_auto_clean_keep_latest_pilots' to true, then the unreleased packages between the newly-live one and the newly-deprecated one are kept on the server as skipped packages.
When something is deleted with auto-clean, the package is deleted from Casper as well as d3, unless the package is in use by a Policy.
The same is true of the package's pre- and post- scripts: if they aren't in use by a Policy or another d3 package, the script's are deleted.
Auto-cleaning is very handy if you have developers who push new editions of a basename frequently.
If this script is defined in d3.conf (admin_make_live_script), it is executed every time a package is made live.
This script is NOT run via the jamf runScript command, and it is NOT run as root. Instead, the script contents are saved into a local temp file, executed, and deleted, all as the user running d3amin.
The script can be used to notify other admins, or do any other task you'd like when a package is made live, just make sure it doesn't need root privileges.
See the d3.conf file for info about what data is available to the script when it runs.
To delete a package from d3:
d3admin delete <basename or edition> <options>
Options can be used to
- delete the Casper scripts associated with the package (if they aren't used elsewhere)
- leave the package in Casper while deleting it from d3
The 'search' action of d3admin will present a list of packages on the server:
d3admin search or d3admin search all
will show the edition of every package in d3, along with its status, when and by whom it was added, and when and by whom it was made live.
To search for basenames matching some string:
d3admin search foo
will find all packages with 'foo' in theirbasename.
The --status option can take 'pilot', 'live', 'deprecated', 'skipped', and 'missing' to limit the list to packages with that status. Use it more than once to see all matching packages.
If you use the --groups option with search, the target is interpreted as a computer group name, rather than a basename, and the packages returned are those which use the group for auto-install, or exclusion scoping:
d3admin search foo --groups or d3admin search --groups foo
(options can be anywhere) This seach will return two lists: all packages that auto-install, and all packages that are excluded, for any computer group who's name contains 'foo'
d3admin can generate reports about d3 receipts on client computers. It does this by querying the JSS for data about installed receipts, so the data is only as up-to-date as the most recent recon for each machine. The "As Of" column of the report indicates the date of the last recon.
d3admin report foo
will list all computers with any edition of basename 'foo'.
The --status option can take 'pilot', 'live', 'deprecated', 'skipped', and 'missing' to limit the list to receipts with that status. Use it more than once to see all matching receipts.
Using --frozen will list all frozen receipts for the basename on all clients.
Using --queue will list items in the puppy-queue with the target basename on all clients.
The --computers option means the report target is interpreted as a computer name, not a basename.
d3admin report --computers pricklepants
will list all receipts on the computer named 'pricklepants' as of its last recon.
The options --status, --frozen, and --queue also work with --computers, so
d3admin report --computers pricklepants daisy --frozen
will show the frozen receipts on computers named pricklepants and daisy.
While d3 is running, the following environment variables may be set. These can be used by scripts (which can be run by policies) to determine the state of d3's world while they're running.
This also allows, e.g. using the same script for both pre- and post- installs. The script can look at D3_RUNNING_PRE_INSTALL and D3_RUNNING_POST_INSTALL to determine which process is happening while it looks at D3_INSTALLING to see what edition is being installed.
It can also look at D3_AUTO_UPDATING, D3_AUTO_INSTALLING, D3_RUNNING _PUPPYTIME to see if it's running during any of those processes, or if none of them, then it's being manually installed.
| ENV | description |
|---|---|
| D3_SYNCING | set to 1 during a sync |
| D3_FORCE | set to 1 if --force was used |
| D3_ADMIN | set to the admin name running d3 |
| D3_DEBUG | set to 1 if client was set to debug mode. |
| D3_AUTO_INSTALLING | set to 1 if an install is an auto-install |
| D3_AUTO_UPDATING | set to 1 if an install is an auto-update |
| D3_UNINSTALLING_BEFORE_INSTALL | set to the edition of the rcpt being UNinstalled |
| D3_RUNNING_PRE_INSTALL | set to the edition of the pkg being installed |
| D3_INSTALLING | set to the edition of the pkg being installed |
| D3_PKG_STATUS | set to the status of the pkg being installed |
| D3_RUNNING_POST_INSTALL | set to the edition of the pkg being installed |
| D3_EXPIRING_PKG | set to the edition of the pkg being expired |
| D3_FINISHED_EXPIRATIONS | set to a space-separated list if editions expired, if any when the expiration policy is runing |
| D3_RUNNING_PRE_REMOVE | set to the edition of the pkg being uninstalled |
| D3_UNINSTALLING | set to the edition of the pkg being uninstalled |
| D3_RUNNING_POST_REMOVE | set to the edition of the pkg being uninstalled |
| D3_NOTIFYING_PUPPIES | set to a space-separated list if editions of items in the puppy-queue when the puppytime notification policy is running |
| D3_RUNNING_PUPPYTIME | set to 1 during logout-installation of pkgs requiring reboot |
| D3_REBOOTING_PUPPIES | set to 1 during the puppy-reboot-policy |