depot3 0.0.0a1 → 3.0.7

data/lib/d3/admin/edit.rb

@@ -0,0 +1,297 @@
+### Copyright 2016 Pixar
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+
+module D3
+  module Admin
+    module Edit
+      extend self
+
+      ### These are all the options that can be edited for an existing d3 package.
+      # This also defines the order they're presented when editing via walkthru.
+      #
+      # This is defined as an array, separate from the keys of PKG_ATTRIBUTE_CONFIG
+      #
+      EDITING_OPTIONS = %w{
+        version
+        revision
+        package_name
+        filename
+        category
+        oses
+        cpu_type
+        reboot
+        removable
+        remove_first
+        prohibiting_process
+        auto_groups
+        excluded_groups
+        pre_install
+        post_install
+        pre_remove
+        post_remove
+        expiration
+        expiration_path
+        description
+      }.map{|i| i.to_sym}
+
+      ### This is how nils and empty strings are displayed to the user
+      NONE = "none"
+
+      ### Continuously loop through displaying the editing menu, and getting
+      ### new values, until the user types 'x'.
+      ###
+      ### @param pkg[D3::Package] the package being edited
+      ###
+      ### @return [Hash] A hash of changes to make to the pkg. Keys are the option
+      ###   symbols from EDITING_OPTIONS, values are new values
+      ###
+      def loop_thru_editing_walkthru (pkg)
+
+        editing_walkthru_state = initial_editing_walkthru_state(pkg)
+
+        walkthru_menu_header = <<-ENDMENU
+------------------------------------
+Editing #{pkg.status} d3 package '#{pkg.edition}'
+JSS Package id: #{pkg.id}
+JSS Package name: #{pkg.package_name}
+Installer filename: #{pkg.filename}
+------------------------------------
+Current Settings => New Settings
+        ENDMENU
+
+        choice = nil
+
+        # loop until the user types an x
+        while choice != "x"
+
+          choice = D3::Admin::Interactive.get_menu_choice( walkthru_menu_header, walkthru_menu_lines(editing_walkthru_state) )
+
+          break if choice == 'x'
+
+          # the number they chose becomes an option key like :reboot
+          chosen_opt = EDITING_OPTIONS[choice]
+
+          # Here's the definition of the option from the OPTIONS hash
+          opt_def = D3::Admin::OPTIONS[chosen_opt]
+
+          # Here the value we're actually editing
+          orig_opt_value = editing_walkthru_state[chosen_opt][:original_value]
+          orig_opt_value ||= opt_def[:default]
+
+          # prompt for a new value and put it in place
+          editing_walkthru_state[chosen_opt][:new_value] = D3::Admin::Interactive.get_value( chosen_opt, orig_opt_value )
+
+
+        end # while choice != x
+
+        # extract just the changes to make
+        changes_to_make = {}
+        editing_walkthru_state.each do |opt, data|
+          comparer = D3::Admin::OPTIONS[opt][:compare]
+          if comparer
+            next if (comparer.call data[:original_value], data[:new_value])
+          else
+            next if (data[:original_value].to_s == data[:new_value].to_s)
+          end
+          changes_to_make[opt] = data[:new_value]
+        end # editing_walkthru_state.each do |opt, data|
+
+        return changes_to_make
+
+      end
+
+      ### A hash of hashes holding the state of the various options
+      ### of a pkg that can be edited during a walkthru.
+      ###
+      ### For each editable option it holds:
+      ### - the original value of the option from the pkg
+      ### - the textual-display version of that value, as created by the matching
+      ###   :display_conversion proc in D3::Admin::EDITING_OPTION_INFO
+      ### - The the new value when the user makes a change.
+      ###
+      ### @param pkg[D3::Package] the pkg being edited
+      ###
+      ### @return [Hash] the walkthru-editing values for the pkg
+      ###
+      def initial_editing_walkthru_state (pkg)
+        editing_walkthru_state = {}
+        EDITING_OPTIONS.each do |o|
+          original_value = pkg.send(o)
+          converter = D3::Admin::OPTIONS[o][:display_conversion]
+          editing_walkthru_state[o] = {
+            :original_value => original_value,
+            :original_value_display => converter ? converter.call(original_value) : original_value,
+            :new_value => original_value
+          } # end hash
+          # set orig value displays that are empty to 'none'
+          editing_walkthru_state[o][:original_value_display] = NONE if editing_walkthru_state[o][:original_value_display].to_s.empty?
+        end # EDITING_OPTIONS.each do |o|
+        return editing_walkthru_state
+      end
+
+      ### Regenerate the walkthru menu lines
+      ###
+      ### @param editing_walkthru_state[Hash] the current state of the values being edited
+      ###
+      ### @return [Array<String>] the lines of the walkthru menu
+      ###
+      def walkthru_menu_lines (editing_walkthru_state)
+
+        display_lines = []
+        EDITING_OPTIONS.each do |opt|
+          # opt is the option symbol, like :reboot
+          opt_def = D3::Admin::OPTIONS[opt]
+          label = opt_def[:label]
+          converter = opt_def[:display_conversion]
+
+          # did the thing change?
+          # compare the old and new either with .to_s and ==
+          # or with the :compare proc defined in EDITING_OPTION_INFO
+          if opt_def[:compare]
+             option_didnt_change = (opt_def[:compare].call editing_walkthru_state[opt][:original_value], editing_walkthru_state[opt][:new_value])
+          else
+             option_didnt_change = (editing_walkthru_state[opt][:original_value].to_s ==  editing_walkthru_state[opt][:new_value].to_s)
+          end
+
+          # no change, so just display the orig value
+          if option_didnt_change
+            val_to_display = editing_walkthru_state[opt][:original_value_display]
+
+          # But if the new val is different, convert it if needed, then show it as "orig => new"
+          else
+            new_value_display = converter ? converter.call(editing_walkthru_state[opt][:new_value]) : editing_walkthru_state[opt][:new_value]
+            new_value_display = NONE if new_value_display.to_s.empty?
+            val_to_display = "#{editing_walkthru_state[opt][:original_value_display]} => #{new_value_display}"
+          end
+
+          # make the line and add it to the array of lines
+          display_lines << "#{label}: #{val_to_display}"
+        end
+        return display_lines
+      end # def update_editing_display_lines(editing_options)
+
+      ### Validate the desired edits from the CLI options
+      ###
+      ### @param cli_options[OpenStruct] the options from the CLI
+      ###
+      ### @return [Hash] A hash of changes to make to the pkg. Keys are the option
+      ###   symbols from EDITING_OPTIONS, values are new values
+      ###
+      def validate_cli_edits (cli_options)
+        changes_to_make = {}
+        EDITING_OPTIONS.each do |opt|
+          if cli_options[opt]
+            opt_check = D3::Admin::OPTIONS[opt][:validate]
+            if opt_check
+              changes_to_make[opt] = D3::Admin::Validate.send(opt_check, cli_options[opt])
+            else
+              changes_to_make[opt] = cli_options[opt]
+            end
+          end # if @options[opt]
+        end #.each do |opt|
+        changes_to_make
+      end
+
+      ### Before making edits, check the possibly new edition in two ways:
+      ### 1) that it doesn't conflict with another edition in d3
+      ### 2) if the original package name contained the original edition
+      ###    and the edition has changed, change the package name to match.
+      ###
+      ### Raises an exception if there are edition conflicts
+      ###
+      ### @param pkg[D3::Package] the package we're editing
+      ###
+      ### @param changes_to_make[Hash] the changes we want to make
+      ###
+      ### @return [Hash] changes_to_make with a possibly new :name
+      ###
+      def check_new_edition (pkg, changes_to_make)
+        new_vers = changes_to_make[:version]
+        new_rev = changes_to_make[:revision]
+        if new_vers or new_rev
+          potential_edition = "#{pkg.basename}-#{new_vers ? new_vers : pkg.version}-#{new_rev ? new_rev : pkg.revision}"
+          unless  pkg.edition == potential_edition
+            # edition conflict?
+            if  D3::Package.all_editions.include? potential_edition
+              raise JSS::AlreadyExistsError, "Can't change version or revision as requested: edition conflict with #{potential_edition}"
+            end
+
+            # name syncing?
+            if pkg.name.include? pkg.edition
+              changes_to_make[:package_name] = pkg.name.sub(pkg.edition, potential_edition ) unless changes_to_make[:package_name]
+            end
+          end # unless
+        end # if new_vers or new_rev
+
+        return changes_to_make
+      end
+
+      ### Before making edits, confirm that the possibly new auto
+      ### or excluded groups don't overlap with each other.
+      ###
+      ### Raises an exception if there are overlaps
+      ###
+      ### @param pkg[D3::Package] the package we're editing
+      ###
+      ### @param changes_to_make[Hash] the changes we want to make
+      ###
+      ### @return [void]
+      ###
+      def check_for_new_group_overlaps (pkg, changes_to_make)
+        new_auto_gs = changes_to_make[:auto_groups]
+        new_excl_gs = changes_to_make[:excluded_groups]
+        bad_groups = []
+        if new_excl_gs and new_auto_gs
+          bad_groups = new_excl_gs & new_auto_gs
+        elsif new_excl_gs
+          bad_groups = new_excl_gs & pkg.auto_groups
+        elsif new_auto_gs
+          bad_groups = new_auto_gs & pkg.excluded_groups
+        end
+        raise "Auto and Excluded groups can't overlap!" unless bad_groups.empty?
+        true
+      end
+
+      ### Make the changes that have been requested with an edit
+      ###
+      ### @param pkg[D3::Package] the package we're editing
+      ###
+      ### @param changes_to_make[Hash] the changes we want to make
+      ###
+      ### @return [void]
+      ###
+      def process_edits (pkg, changes_to_make)
+        changes_to_make.each do |opt, new_val|
+          setter = (opt.to_s + "=").to_sym
+          pkg.send setter, new_val
+        end
+        pkg.save
+        pkg.update_master_filename D3::Admin::Auth.rw_credentials(:dist)[:password] if changes_to_make[:filename]
+      end
+
+    end # module edit
+  end # module Admin
+end # module D3
+

data/lib/d3/admin/help.rb

@@ -0,0 +1,396 @@
+### Copyright 2016 Pixar
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+
+module D3
+  module Admin
+    # This just exists to get the very lengthy help texts out of the d3admin and
+    # d3 executables.
+    module Help
+      extend self
+
+      USAGE = "Usage: d3admin action target [options]"
+
+      ### Return the d3amin help text
+      ###
+      ### @return [String] the d3admin help text
+      ###
+      def help_text
+        helptxt = <<-ENDHELP
+
+#{USAGE}
+
+=== Actions <target> ===
+
+  add <basename>                     Add a new pilot package
+  edit <basename/edition>            Change properties of existing package
+  live <edition>                     Make existing pilot package live
+  delete <basename/edition>          Delete a package
+  info <basename/edition>            Show details of an package
+  search <basename/group>            List matching pkgs on the server
+  report <basename/computer>         Report about receipts on computers
+  config <setting/display>           d3admin configutation on this machine
+  help                               Show this help.
+
+=== Options ===
+
+General:
+  -w, --walkthru                     Interactively prompt for all options.
+  -a, --auto-confirm                 Don't ask for confirmation before acting
+  -h, --help                         Show this help text
+  -H, --extended-help                Show extended help
+  -D, --debug                        Show debug info and ruby backtraces
+
+Action add:
+  -i, --import <name or id>          Import an existing JSS package
+  -W, --workspace <path>             Folder in which to build .dmgs & .pkgs
+  -I, --no-inherit                   Don't inherit values from last package
+  -s, --source-path <path>           Path to a .pkg, .dmg, or root-folder
+  --dmg                              Build a .dmg, rather than a .pkg
+  --preserve-owners                  Keep the ownership of contents in built .pkgs
+  -p, --pkg-id <pkgid>               Apple pkg-identifier for built .pkgs
+
+Action add and edit:
+  -v, --version <version>            Version of the thing installed
+  -r, --revision <revision>          Sequential packaging of the same version
+  -n, --package-name <name>          The JSS 'display name' of the package
+  -f, --filename <name>              The filename on the distribution point
+  -d, --description <desc>           A textual description of this package
+  -e, --pre-install <script>         Name, id, or path to pre-install script
+  -t, --post-install <script>        Name, id, or path to post-install script
+  -E, --pre-remove <script>          Name, id, or path to pre-remove script
+  -T, --post-remove <script>         Name, id, or path to post-remove script
+  -g, --auto-groups <groups>         Computer groups to get this pkg automatically
+  -G, --excluded-groups <groups>     Computer groups that can't see this pkg
+  -x, --prohibiting-process <proc>   Process name that prevents installation
+  -R, --reboot <y/n>                 Reboot required after install, puppies!
+  -F, --remove-first <y/n>           Uninstall older versions before installing
+  -u, --removable <y/n>              Can this package be uninstalled?
+  -o, --oses <oses>                  OS limitations for installation.
+  -c, --cpu <type>                   Limit installation to 'intel' or 'ppc'
+  -C, --category <category>          The JSS Category for this package
+  -X, --expiration <days>            Auto-uninstall if unused for <days>
+  -P, --expiration-path <path>       Path to executable that must be used
+
+Action delete:
+  --delete-scripts                   Delete scripts associated with this pkg
+  --keep-in-jss                      Delete from d3 but leave in the JSS
+
+Action search or report:
+  -S, --status <status>              Limit package list to this status
+  --groups                           Target is a group name. Shows packages
+                                       auto-installed or excluded for group
+
+Action report:
+  -S, --status <status>              Limit receipt list to this status
+  -z, --frozen                       Limit receipt list to frozen receipts
+  -q, --queue                        List puppy queue items rather than rcpts
+  --computers                        Target is a computer name. Reports
+                                        rcpts/puppies on that computer.
+
+For details use -H or --extended-help
+
+See also: https://github.com/PixarAnimationStudios/depot3/wiki/Admin
+
+ENDHELP
+      end # help text
+
+
+      ### Return the d3amin help text
+      ###
+      ### @return [String] the d3admin help text
+      ###
+      def extended_help_text
+        helptxt = <<-ENDHELP
+
+d3admin is a tool for administering packages in d3, a package/patch
+management & deployment tool that enhances the package-handling capabilities
+of the Casper Suite from JAMF Software, LLC.
+
+For detailed documentation see:
+https://github.com/PixarAnimationStudios/depot3/wiki/Admin
+
+Important Terms:
+
+- basename:   A word used to identify all packages that install any version of
+              the same thing. E.g. 'filemaker' or 'transmogrifier' When a
+              basename is used to specify a package, it refers to the currently
+              live package for the basename. (see below)
+
+- edition:    A unique identifier for a package or receipt in d3. It is made of
+              the basename, version, and revision, joined by dashes.
+              E.g. 'transmogrifier-2.2.1-2'
+              Editions specify individual packages regardless of their status.
+
+- live:       Each edition has a status: pilot, live, skipped, deprecated, or
+              missing. Only one edition per basename can be 'live' a a time.
+              When an edition is made live, it's approved for general deployment
+              and is the edition installed with 'd3 install <basename>'. It will
+              also auto-install on computers in the packages auto-groups, and it
+              will auto-update on any computers with older editions of the same
+              basename already installed.
+
+- walkthru:   Any action can take the --walkthru option and you'll be prompted
+              for targets (if needed) and options.
+              Without --walkthru, you must provide all values with command-line
+              options. Anything not on the command-line will use a default or
+              inherited value, or cause an error if the option was required.
+
+#{USAGE}
+
+When refering to a package on the server, a basename imples the currently live
+edition for that basename. Refering to a package by edition specifies an
+individual package regardless of status.
+
+
+=== Actions and their required targets & options ===
+
+  add      Add a new pilot package to d3
+             Target = basename unless -w
+             Without -w, requires -v, -r, & -s
+
+  edit     Change properties of existing package in d3
+             Target = basename or edition unless -w
+
+  live     Make existing pilot package live
+             Target = edition unless -w
+
+  delete   Delete an existing package from d3
+             Target = basename or edition unless -w
+
+  info     Show details of an package in d3
+             Target = basename or edition unless -w
+
+  search   Search for and list packages in d3.
+              Target = search text (RegExp matching)
+              No target = list all packages unless -w
+
+  report   Report about d3 receipts or puppies on computers.
+             Target = basename, or computer name unless -w
+
+  config   Set up server info and default values for d3admin.
+             Target = all, jss, db, dist, workspace,
+             pkg-id-prefix or display. Defaults to all
+
+             Using 'display' prints out the current admin config settings.
+
+             Runs 'all' automatically on first run.
+
+  help     Show this help. Use -H for extended help.
+
+
+NOTE: Any action that requires stored passwords will prompt for your
+keychain password if your login keychain is currently locked.
+
+=== Options ===
+
+Non-required options for add will use inherited or default values if unspecified.
+
+General:
+
+  -w, --walkthru                     Interactively prompt for all options.
+                                       Options provided on the commandline are
+                                       ignored. Without -w, anything NOT provided
+                                       on the command-line will use a default or
+                                       inherited value or will raise an error.
+
+  -a, --auto-confirm                 Don't ask for confirmation before making
+                                       changes. For use in automation.
+                                       BE VERY CAREFUL
+
+  -H, --help                         Show this help text
+
+  -D, --debug                        Show LOTS of debugging info about whats
+                                       happening. If there's a Ruby error,
+                                       show the backtrace. Useful when reporting
+                                       problems.
+
+Action add:
+
+  -i, --import <name or id>          When the action is 'add', import an existing
+                                       JSS package into d3 by display-name or id.
+                                       Requires -w or  -v & -r
+
+  -W, --workspace <path>             Folder in which to build .dmgs & .pkgs
+                                       default is your home folder.
+                                       Preserved between uses of d3admin.
+
+  -I, --no-inherit                   Don't inherit default values from most
+                                       recent package with the same basename.
+
+  -s, --source-path <path>             Path to a .pkg, .dmg, or root-folder
+                                       from which to build one
+
+  --dmg                          When building from a root folder, build
+                                       a .dmg, rather than the default .pkg
+
+  --preserve-owners                  When building .pkgs, keep the ownership of
+                                       the pkg-root folder. Default is to let
+                                       the OS set ownership to standards based
+                                       upon where items are installed.
+
+  -p, --pkg-id <pkgid>               When building .pkgs, the apple package
+                                       identifier, e.g. 'com.mycompany.app'
+                                       Defaults to a prefix, plus the basename.
+                                       The prefix is either the the apple_pkg_id_prefix
+                                       setting from the d3admin config, or
+                                       '#{D3::Admin::DFT_PKG_ID_PREFIX}'
+
+Action add and edit:
+
+  -v, --version <version>            Version of the thing installed by the
+                                       package, e.g. "2.5", "1.1a3".
+                                       May not contain a '-', which will be
+                                       converted to '_'
+
+  -r, --revision <revision>          Package-revision.
+                                       This integer represents how many times
+                                       a particular version of a basename has
+                                       been added to d3.
+
+  -n, --package-name <name>          The JSS 'display name' of the package.
+                                       Must be unique in the JSS
+                                       Defaults to <edition>.<pkg_type>
+                                       e.g. myapp-2.3a1-2.pkg
+
+  -f, --filename                     The name of the installer file on the
+                                       master distribution point. When uploading,
+                                       the file will be renamed to this.
+                                       If the installer is a .pkg bundle, it
+                                       will be zipped, and '.zip' appended
+                                       automatically when uploaded.
+                                       Defaults to <edition>.<pkg_type>
+                                       e.g. myapp-2.3a1-2.pkg
+
+  -d, --description <desc>           A textual description of this package,
+                                       and any notes or comments about it.
+
+  -e, --pre-install <script>         The name or id of an existing JSS script,
+                                       or the path to a file with a new script.
+                                       This script is run before installing.
+                                       Use "n" for 'none'.
+                                       See the full documentation for details.
+
+  -t, --post-install <script>        As for pre-install, but the script to run
+                                       after installing the package.
+
+  -E, --pre-remove <script>          As for pre-install, but the script to run
+                                       before uninstalling the package.
+
+  -T, --post-remove <script>         As for pre-install, but the script to run
+                                       after uninstalling the package.
+
+  -g, --auto-groups <groups>        Comma-separated list of JSS computer groups
+                                       whose members get this pkg automatically.
+                                       Use '#{D3::STANDARD_AUTO_GROUP}'
+                                       to install on all machines.
+                                       Use "n" for 'none'.
+
+  -G, --excluded-groups <groups>      Comma-separated list of JSS computer groups
+                                       whose members can't install this pkg
+                                       without using force.
+                                       Use "n" for 'none'.
+
+  -x, --prohibiting-process <proc>   Specify a name to match with process names
+                                       as output by `/bin/ps -A -c -o comm`.
+                                       If a match is found at install time,
+                                       prevents installation. Use "n" for 'none'
+
+  -R, --reboot <y/n>                 Reboot is required after install.
+                                       (PuppyTime!)
+                                       Default is 'n'
+
+  -u, --removable <y/n>              Can this package be uninstalled?
+                                       Default is 'y'
+
+  -F, --remove-first  <y/n>          Uninstall older versions before installing
+                                       this one, if they are removable.
+                                       Default is 'n'  (installs over the top)
+
+  -o, --oses <oses>                  Comma-separated list of OS version to allow
+                                       installation of this package.
+                                         e.g. 10.5.8, 10.6.x
+                                       Use '>=' to set a min. OS version
+                                         e.g. >=10.6.0
+                                       Use "n" for no limitation
+
+  -c, --cpu <type>                   Limit to cpu type: 'ppc' or 'intel'
+                                       Use "n" for no limitation.
+
+  -C, --category <category>          The JSS Category for this package
+                                       Use "n" for none
+
+  -X, --expiration <days>            How many days of no use before this package
+                                       uninstalls itself. Pkg must be removable,
+                                       and expiration must be allowed in the
+                                       client config.
+
+  -P, --expiration-path <path>       The path to the executable the must be used
+                                       within the expiration period to avoid
+                                       being uninstalled
+
+Action delete:
+
+  --delete-scripts                   Delete any scripts associated with this pkg
+                                       if they aren't in use elsewhere. Those in
+                                       use will be reported.
+
+  --keep-in-jss                      Leave the package in the JSS after deleting
+                                       it from d3
+
+
+Action search:
+
+  -S, --status <status>              Limit the packages listed to those with
+                                       the given status. Can be used multiple
+                                       times to see multiple statuses.
+
+  --groups                           Instead of basenames, search computer
+                                       group names and report packages scoped
+                                       by those groups for auto-install or
+                                       exclusion.
+
+Action report:
+
+  -S, --status <status>              Limit the receipts listed to those with
+                                       the given status. Can be used multiple
+                                       times to see multiple statuses.
+
+  -z, --frozen                       Limit the receipts listed to frozen ones.
+
+  -q, --queue                        Report pending puppy installs rather than
+                                       receipts.
+
+  --computers                        The target of the report is a computer name
+                                       and the report is about receipts or
+                                       pending puppy installs on that computer.
+
+
+ENDHELP
+      end # extended help text
+
+    end # module help
+  end # module admin
+end # module D3
+