xolo-admin 2.0.3 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8637742b96fa6e20b3d2d781f6c3e6d7c19cf0fbaa9bd4d39625cf9738f06845
-  data.tar.gz: af15092c906bd833441229bccc8d2944b99dbc035fc29a6ddcb3985979ab4f77
+  metadata.gz: 5a18c9e9384018067cb93f0f5a1a158c4934841d05661b66911d8d95a2b4985e
+  data.tar.gz: 3fa6cf5701caf06ccce8f8e4b7226a55cd4fb0d61451764b15f9e383c9643034
 SHA512:
-  metadata.gz: d73169bf141bf0d98d2b05c586673e073d2d43785418bbfe57c34a4876637f1e6fca2e5b91f3739ec35d563bc4d254e57f58d6e61d629814ed5f47bfe750e2d9
-  data.tar.gz: a7edfa0ddc811772c3dc12c3621bdf200b01630f4c0605190ee8c07e4abbb7065bda17be11cf0dd3857dfb5b302a60641225a4cbd2397a5fbae0de1758f9dba4
+  metadata.gz: 0b23b00c96d3c21971507c9b7e9f669ef37f09912d9332de34c9cb2d7cb02f38eec2dc8bdb956ac4db3cecfcb13271243a51a6c8bf77b42e4e000315d50225e3
+  data.tar.gz: 83023a43c98543cffa21059763f1759be7723c1da99b5174e4b57a4e3000543345ba2323c095b71cfd56fe40d87b66628f26ade13f0348c0678705b39e442c5a

data/data/client/xolo

@@ -159,10 +159,24 @@ Options:
   -V, --version:     Show the version of xolo.
 
 Commands:
-  install, i <title>[=<version>] [<title2>[=<version2>] ...]
-    Install a title, or specific version thereof (e.g. a version currently in pilot)
+  install, i <title> [<version>] [...]
+  install, i <title>[=<version>] [...]
+
+    Install one or more titles, or specific versions thereof (e.g. currently in pilot)
     If no version is specified, the currently released version will be installed.
 
+    To install more than one item at a time, use 'title=version' if you need a non-
+    released version of the title.
+
+    So 'install <title1> <title2>' installs the current release of each title, and
+    'install <title1> <version1>'  installs version1 of title1, but
+    'install <title1>=<version1> <title2>' installs version1 of title1 and the
+    current release of title2. You can install as many items as needed this way.
+
+    In short, you can always use '=' between titles and versions, but you can
+    only omit it when the there are only two arguments and they are a title
+    and a version.
+
   uninstall, u <title> [<title2> ...]
     Uninstall a title, if possible. Not all titles are uninstallable via xolo.
 
@@ -255,8 +269,24 @@ function parse_cli() {
   command=$1
   [[ ${#@} -gt 0 ]] && shift
 
+  # the remaining positional parameters as an array called targets
+  # It'll either be exactly 1 item: title
+  # or exactly 2 items containing no '=' : title, version
+  # or exactly 2 items containing no '=' : title, title
+  # or any number if items in the form: title[=version]  where the =version is optional.
   targets=("${(@)@}")
 
+  # if targets has exactly 2 items, and neither of them contains
+  # '=' and the second one isn't an existing title then treat
+  # them as the title and a version and reset 'targets' to be 'title=version'
+  if [[ "$#targets" == 2  ]] \
+    && [[ "$targets[1]" != *"$TITLE_VERSION_SEPARATOR"* ]] \
+    && [[ "$targets[2]" != *"$TITLE_VERSION_SEPARATOR"* ]] \
+    && ! echo "$(all_xolo_titles)" | grep -qE "^${targets[2]}$"  ; then
+
+    targets=("$targets[1]=$targets[2]")
+  fi
+
   debug "Parsed command line:"
   debug "..show_help is: $show_help"
   debug "..be_verbose is: $be_verbose"
@@ -275,6 +305,9 @@ function parse_cli() {
 #################################
 function parse_title_and_version() {
   local arg=$1
+  unset title_is_valid
+  unset version_is_valid
+
   debug "Parsing title and version from arg: '$arg'"
 
   if [[ "$arg" == *"$TITLE_VERSION_SEPARATOR"* ]] ; then
@@ -786,9 +819,13 @@ function refresh_client_data() {
 # validate that the title exists
 ###############################
 function validate_title() {
+
   # if we've already validated the title, we're done
   [[ -n "$title_is_valid" ]] && return
 
+  # use passed arg if needed
+  [[ -z "$title" ]] && title=$1
+
   debug "Validating title: $title"
 
   # die if no title given
@@ -823,7 +860,7 @@ function validate_version() {
   all_versions=$(versions_for_title $title)
   debug "All versions for title $title:\n$all_versions"
   # [[ $all_versions =~ (^|\n)$version($|\n) ]] || die "No such version: $version"
-  echo "$all_versions" | grep -q "^$version$" || die "No such version: $version"
+  echo "$all_versions" | grep -q "^$version$" || die "No such version '$version' for title '$title'"
   version_is_valid=1
 }
 

data/lib/xolo/admin/command_line.rb

@@ -398,6 +398,7 @@ module Xolo
               opt opt_key, desc, short: deets[:cli], type: type, required: required, multi: deets[:multi]
             end # opts_to_use.each
           end # if cmd_opts
+          conflicts :subscribed, :managed if cmd == Xolo::Admin::Options::LIST_TITLES_CMD
         end # Optimist.options
       end
 

data/lib/xolo/admin/connection.rb

@@ -19,8 +19,8 @@ module Xolo
       ##############################
       ##############################
 
-      TIMEOUT = 300
-      UPLOAD_TIMEOUT = 1800
+      TIMEOUT = 1800
+      UPLOAD_TIMEOUT = 3600
       OPEN_TIMEOUT = 10
 
       PING_ROUTE = '/ping'
@@ -151,8 +151,18 @@ module Xolo
 
         # this proc every time we get a chunk, just print it to stdout
         # and make note if any of them conain an error
+        # every 10 secs with no real data, we get ':heartbeat'
+        # which we use to display dots on a line as we wait for more data.
+        need_newline = nil
+
         streaming_proc = proc do |chunk, _size, _env|
-          puts chunk
+          if chunk == ':heartbeat'
+            print '.'
+            need_newline = "\n"
+          else
+            puts "#{need_newline}#{chunk}"
+            need_newline = nil
+          end
           @streaming_error ||= chunk.include? STREAMING_OUTPUT_ERROR
         end
 

data/lib/xolo/admin/interactive.rb

@@ -21,7 +21,7 @@ module Xolo
         'vim (vi)' => '/usr/bin/vim',
         'mg (emacs)' => '/usr/bin/mg',
         'pico (nano)' => '/usr/bin/pico'
-      }
+      }.freeze
 
       MULTILINE_HEADER_SEPARATOR = "\nDO NOT EDIT anything above the next line:\n=================================="
 
@@ -215,6 +215,15 @@ module Xolo
         'N/A until Patch Source is set'
       end
 
+      # @return [String, nil] If a string, a reason why the given menu item is not available now.
+      #   If nil, the menu item is displayed normally.
+      ##############################
+      def auto_release_delay_na
+        return if walkthru_cmd_opts[:subscribed] && !walkthru_cmd_opts[:autopkg_recipe].pix_empty?
+
+        'N/A unless title is Subscribed and uses an AutoPkg Recipe'
+      end
+
       # @return [String, nil] If a string, a reason why the given menu item is not available now.
       #   If nil, the menu item is displayed normally.
       ##############################
@@ -251,7 +260,7 @@ module Xolo
       #   If nil, the menu item is displayed normally.
       ##############################
       def expiration_paths_na
-        'N/A unless expiration is > 0' unless walkthru_cmd_opts[:expiration].to_i.positive?
+        'N/A unless expiration days is > 0' unless walkthru_cmd_opts[:expiration].to_i.positive?
       end
 
       # @return [String, nil] If a string, a reason why the given menu item is not available now.

data/lib/xolo/admin/options.rb

@@ -182,7 +182,7 @@ module Xolo
       HELP_CMD = 'help'
 
       # server-admin commands
-      SERVER_CLEANUP_CMD = 'run-server-cleanup'
+      SERVER_MAINT_CMD = 'run-server-maint'
       UPDATE_CLIENT_DATA_CMD = 'update-client-data'
       ROTATE_SERVER_LOGS_CMD = 'rotate-server-logs'
       SET_SERVER_LOG_LEVEL_CMD = 'set-server-log-level'
@@ -198,6 +198,74 @@ module Xolo
       TARGET_TITLE_PLACEHOLDER = Xolo::Admin::Title::TARGET_TITLE_PLACEHOLDER
       TARGET_VERSION_PLACEHOLDER = 'TARGET_VERSION_PH'
 
+      LIST_TITLES_OPTIONS = {
+        subscribed: {
+          label: 'Subscribed Only',
+          cli: :s,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only 'subscribed' titles. Can be combined with all other options except --managed.
+          ENDDESC
+        },
+
+        managed: {
+          label: 'Managed Only',
+          cli: :m,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only 'managed' titles. Can be combined with all other options excepted --subscribed.
+          ENDDESC
+        },
+
+        autopkg: {
+          label: 'AutoPkg Only',
+          cli: :a,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only titles configured for AutoPkg. Can be combined with all other options.
+          ENDDESC
+        },
+
+        pilots: {
+          label: 'Pilots Only',
+          cli: :p,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only titles with pending pilot (un-released) versions. Use 'list-versions' to see details for a title. Can be combined with all other options.
+          ENDDESC
+        },
+
+        self_service: {
+          label: 'Self Service Installs Only',
+          cli: :i,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only titles that are available for initial instalation via Self Service. To see those with updates depolyed via Self Service, use --self-service-updates.
+          ENDDESC
+        },
+
+        self_service_updates: {
+          label: 'Self Service Updates Only',
+          cli: :u,
+          type: :boolean,
+          validate: :validate_boolean,
+          default: false,
+          desc: <<~ENDDESC
+            Show only titles that are available for updates via Self Service. To see those with initial installation via Self Service, use --self-service.
+          ENDDESC
+        }
+      }.freeze
+
       PATCH_REPORT_OPTIONS = {
         summary: {
           label: 'Summary Only',
@@ -410,7 +478,7 @@ module Xolo
         LIST_TITLES_CMD => {
           desc: 'List all software titles.',
           display: LIST_TITLES_CMD,
-          opts: {},
+          opts: LIST_TITLES_OPTIONS,
           arg_banner: :none,
           process_method: :list_titles,
           target: :none
@@ -466,6 +534,16 @@ module Xolo
             all policies and patch policies related to this title and its versions.
             If a computer doesn't have any version of the title, this will prevent
             it from being installed via xolo (it will be 'frozen' in that state).
+
+            Excluding vs Freezing:
+              - Excluded Groups (via the --excluded-groups option for titles) are
+                how to prevent members from accessing titles in Xolo. They can be
+                thought of as 'freezing for groups'
+
+              - Freezing (via 'xadm freeze...') is how to prevent individual computers
+                from accessing titles in Xolo. It can be thought of as 'exclusion for
+                individual computers'
+
           ENDLONG
           display: "#{FREEZE_TITLE_CMD} title [--users] target [target ...] ",
           opts: FREEZE_THAW_OPTIONS,
@@ -759,21 +837,29 @@ module Xolo
           process_method: :server_status
         },
 
-        SERVER_CLEANUP_CMD => {
-          desc: "[Server Admins Only] Run the server's cleanup process now.",
+        SERVER_MAINT_CMD => {
+          desc: "[Server Admins Only] Run the server's nightly maintenance process now.",
           long_desc: <<~ENDLONG,
             Requires server-admin privileges.
-            Once a version of a title is released, the preveiously released
-            version is marked as 'deprecated', and any older unreleased versions
-            are marked as 'skipped'. A nightly task will then delete all skipped
-            versions from xolo, as well as deprecated versions that have been than
-            deprecated more than some number of days, as configured configured on
-            the server. Running this command will do that cleanup now.
+            Performs various nightly tasks immediately.
+
+            These tasks happen automatically between 2-3am:
+            - Accepts lingering Title Editor Extension Attributes, if the server is
+              configured to do so.
+            - Auto-releases appropriate verions of titles configured to do so.
+            - Cleans up old versions:
+              Once a version of a title is released, the preveiously released
+              version is marked as 'deprecated', and any older unreleased versions
+              are marked as 'skipped'. The nightly maintenance task will then:
+              - delete all skipped versions of the title
+              - delete all deprecated versions that have been than deprecated more
+                than some number of days, as configured configured on the server.
+              - email title owners about pending pilots more than some number of days old.
           ENDLONG
-          display: SERVER_CLEANUP_CMD,
+          display: SERVER_MAINT_CMD,
           opts: {},
           arg_banner: :none,
-          process_method: :server_cleanup,
+          process_method: :server_maint,
           confirmation: true
         },
 

data/lib/xolo/admin/processing.rb

@@ -26,7 +26,7 @@ module Xolo
       # Routes for server admins
 
       SERVER_STATUS_ROUTE = '/maint/state'
-      SERVER_CLEANUP_ROUTE = '/maint/cleanup'
+      SERVER_MAINT_ROUTE = '/maint/maint-start'
       SERVER_ROTATE_LOGS_ROUTE = '/maint/rotate-logs'
       SERVER_UPDATE_CLIENT_DATA_ROUTE = '/maint/update-client-data'
       SERVER_LOG_LEVEL_ROUTE = '/maint/set-log-level'
@@ -145,18 +145,24 @@ module Xolo
       # @return [String] the string to display for the search result
       ###################################
       def title_search_result_str(title, one_line: false)
+        title_type = []
+        title_type << (title.subscribed? ? 'subscribed' : 'managed')
+        title_type << 'autopkg' if title.autopkg_enabled?
+        title_display = "#{title.title} (#{title_type.join(',')})"
+
         versions = versions_str(title)
+
         if one_line
-          [title.title, title.display_name, title.publisher, title.contact_email, versions]
+          [title_display, title.display_name, title.publisher, title.contact_email, versions]
         else
           titleout = +'#---------------------------------------'
-          titleout << "\nTitle: #{title.title}"
+          titleout << "\nTitle: #{title_display}"
           titleout << "\nDisplay Name: #{title.display_name}"
           titleout << "\nPublisher: #{title.publisher}"
           titleout << "\nApp: #{title.app_name}\nBundleID: #{title.app_bundle_id}" if title.app_name
           titleout << "\nVersions: #{versions}"
-          titleout << "\nDescription:"
-          titleout << "\n#{title.description}"
+          titleout << "\nContact: #{title.contact_email}"
+          titleout << "\nDescription: #{title.description}"
           titleout
         end # json?
       end
@@ -211,16 +217,38 @@ module Xolo
           return
         end
 
-        report_title = 'All titles in Xolo'
-        header = %w[Title Created By SSvc? Released Latest]
+        type = opts_to_process.subscribed ? ' subscribed' : nil
+        type ||= opts_to_process.managed ? ' managed' : nil
+        autopkg = opts_to_process.autopkg ? ' autopkg' : nil
+        pilots = opts_to_process.pilots ? ' with unreleased pilots' : nil
+
+        ssvc =
+          if opts_to_process.self_service && opts_to_process.self_service_updates
+            ' installed or updated via Self Service'
+          elsif opts_to_process.self_service
+            ' installed via Self Service'
+          elsif opts_to_process.self_service_updates
+            ' updated via Self Service'
+          end
+
+        report_title = "All#{type}#{autopkg} titles in Xolo#{pilots}#{ssvc}"
+
+        titles.select!(&:subscribed?) if opts_to_process.subscribed
+        titles.reject!(&:subscribed?) if opts_to_process.managed
+        titles.select!(&:autopkg_recipe) if opts_to_process.autopkg
+        titles.select!(&:pending_pilots?) if opts_to_process.pilots
+        titles.select!(&:self_service?) if opts_to_process.self_service
+        titles.select!(&:self_service_updates?) if opts_to_process.self_service_updates
+
+        header = %w[Title Created By SSvc? Latest Released]
         data = titles.map do |t|
           [
             t.title,
             t.creation_date.to_date,
             t.created_by,
             t.self_service || false,
-            t.released_version,
-            t.latest_version
+            t.latest_version,
+            t.released_version
           ]
         end
         data.sort_by! { |d| d[0].downcase } # sort by title
@@ -230,6 +258,16 @@ module Xolo
         handle_processing_error e
       end
 
+      # @param title [Xolo::Admin::Title] The title in question
+      # @return [Boolean] Does a given Title object have pilots?
+      ###########################
+      def pending_pilots?(title)
+        return false if title.version_order.pix_empty?
+        return false if title.released_version == title.version_order.first
+
+        true
+      end
+
       # Add a title to Xolo
       #
       # @return [void]
@@ -487,16 +525,19 @@ module Xolo
           return
         end
 
-        report_title = "All versions of '#{cli_cmd.title}' in Xolo"
+        report_title = "All versions of '#{cli_cmd.title}' in Xolo.  ** = No .pkg uploaded"
         header = %w[Vers Created By Released By Status]
         data = versions.sort_by(&:creation_date).map do |v|
+          no_pkg = v.pkg_to_upload.pix_empty? && v.jamf_pkg_file.pix_empty?
+          status = no_pkg ? "#{v.status} **" : v.status
+
           [
             v.version,
             v.creation_date.to_date,
             v.created_by,
             v.release_date&.to_date,
             v.released_by,
-            v.status
+            status
           ]
         end
         show_text generate_report(data, header_row: header, title: report_title)
@@ -528,7 +569,7 @@ module Xolo
         # Upload the pkg, if any?
         upload_pkg(new_vers) unless title_obj.autopkg_enabled?
 
-        speak 'It can take up to 15 minutes for the version to be available via Jamf and Self Service.'
+        speak 'It can take up to 15 minutes for the version to be available for use. Please do not release it before then'
       rescue StandardError => e
         handle_processing_error e
       end
@@ -977,14 +1018,14 @@ module Xolo
         handle_processing_error e
       end
 
-      # kick off server cleanup
+      # kick off server maintenance
       #
       # @return [void]
       ###############################
-      def server_cleanup
-        return unless confirmed? 'Run the Xolo Server cleanup process'
+      def server_maint
+        return unless confirmed? 'Run the Xolo Server maintenance process'
 
-        result = server_cnx.post(SERVER_CLEANUP_ROUTE).body
+        result = server_cnx.post(SERVER_MAINT_ROUTE).body
         puts result[:result]
       rescue StandardError => e
         handle_processing_error e
@@ -1150,7 +1191,6 @@ module Xolo
         puts "Saved 'xolo' client tool to '#{dest}'"
       end
 
-      # run the cleanup
       # get the /test route to do whatever testing it does.
       # during testing - this will return all kinds of things.
       #

data/lib/xolo/admin/progress_history.rb

@@ -34,7 +34,7 @@ module Xolo
       PROGRESS_HISTORY_FILENAME = 'com.pixar.xolo.admin.progress_history.yaml'
 
       # prog files on the server last 3 days, add an extra to
-      # account for timing of daily cleanup on the server.
+      # account for timing of daily maint on the server.
       # if the file is already gone from the server, we'll tell
       # the user
       PROGRESS_FILE_LIFETIME = 4 * 24 * 3600

data/lib/xolo/admin/validate.rb

@@ -366,6 +366,26 @@ module Xolo
         raise_invalid_data_error val, TITLE_ATTRS[:uninstall_script][:invalid_msg]
       end
 
+      # validate a title auto_release_delay:
+      # - a non-negative integer?
+      # OR
+      # - 'none' to unset the value
+      #
+      # @param val [Object] The value to validate
+      #
+      # @return [String, Integer] The valid value
+      ###########################
+      def validate_auto_release_delay
+        return if val == Xolo::NONE
+
+        if val.pix_integer?
+          val = val.to_i
+          return val unless val.negative?
+        end
+
+        raise_invalid_data_error val, TITLE_ATTRS[:auto_release_delay][:invalid_msg]
+      end
+
       # validate a title uninstall ids:
       # - an array of package identifiers
       # OR
@@ -449,6 +469,27 @@ module Xolo
         raise_invalid_data_error bad_grps, TITLE_ATTRS[:excluded_groups][:invalid_msg]
       end
 
+      # validate an array  of jamf groups to use as targets.
+      # 'none' is also acceptable
+      #
+      #
+      # @param val [Array<String>] The value to validate:  names of jamf comp.
+      #   groups, or 'none'
+      #
+      # @return [Array<String>] The valid value
+      ##########################
+      def validate_target_groups(val)
+        val = [val] unless val.is_a? Array
+        return [] if val.include? Xolo::NONE
+
+        bad_grps = bad_jamf_groups(val)
+        return val if bad_grps.empty?
+
+        bad_grps = "No Such Groups: #{bad_grps.join(Xolo::COMMA_JOIN)}"
+
+        raise_invalid_data_error bad_grps, TITLE_ATTRS[:target_groups][:invalid_msg]
+      end
+
       # validate an array  of jamf groups to use as MDM deployment targets.
       # 'none' is also acceptable
       #
@@ -914,6 +955,9 @@ module Xolo
 
         # if self-service category given, must be in self-service
         validate_title_consistency_ssvc_needs_category(opts)
+
+        # if auto_release_delay is non-negative integer, must be subbscribed and autopkg
+        validate_title_consistency_auto_release_delay(opts)
       end # title_consistency(opts)
 
       # Complain about using options not meant for the chosen title type
@@ -1040,6 +1084,19 @@ module Xolo
         raise_consistency_error msg
       end
 
+      # if auto_release_delay, must be subbscribed and autopkg
+      #
+      # @param opts [OpenStruct] the current options
+      #
+      # @return [void]
+      #######
+      def validate_title_consistency_auto_release_delay(opts)
+        return if opts[:auto_release_delay].pix_empty? || opts[:auto_release_delay] == Xolo::NONE
+        return if current_title_type(opts) == Xolo::SUBSCRIBED && !opts[:autopkg_recipe].pix_empty?
+
+        raise_consistency_error '--auto-release-delay can only be used with subscribed titles that use autopkg.'
+      end
+
       # If using app_name and bundle id, both must be given
       #
       # @param opts [OpenStruct] the current options

data/lib/xolo/core/base_classes/title.rb

@@ -458,6 +458,31 @@ module Xolo
             ENDDESC
           },
 
+          # @!attribute auto_release_delay
+          #   @return [String] 'none' or an integer in string. How many days before new versions are automatically released?
+          #     Applies only to subscribed titles with autopkg recipes.
+          auto_release_delay: {
+            label: 'Automatic Release Delay',
+            cli: :A,
+            type: :string,
+            walkthru_na: :auto_release_delay_na,
+            changelog: true,
+            invalid_msg: "Must be a non-negative integer, or '#{Xolo::NONE}'.",
+            desc: <<~ENDDESC
+              Specify how many days after a new version appears before it is automatically released from pilot.
+
+              This option is only available for titles that are both subscribed, and have an AutoPkg recipe configured. Any other title requires manual release of pilot versions using `xadm release <title> <version>`.
+
+              Setting this to 7 means that a week after a new version appears as a pilot, it will automatically be released as if someone did `xadm release <title> <version>`. The delay period should be used for piloting the version, either automatically using pilot-groups, or manually. *** USE WITH CAUTION ***
+
+              Setting it to zero means that new versions will be released at the next nightly auto-release task. *** USE WITH EXTREME CAUTION ***
+
+              To unset, meaning versions are never auto-released, use '#{Xolo::NONE}'
+
+              Auto-release happens during the server's nightly maintenance between 2-3am.
+            ENDDESC
+          },
+
           # @!attribute pilot_groups
           #   @return [Array<String>] Jamf groups that will automatically get new versions installed or
           #     updated when added, for piloting
@@ -474,7 +499,7 @@ module Xolo
             desc: <<~ENDDESC
               One or more Jamf Computer Groups whose members will automatically have new versions installed or updated for testing before it is released.
 
-              These groups affect both the initial installation of and updates to a title when a version is added, before it is released.
+              These groups affect both the initial installation and updates of a title when a version is added, before it is released.
 
               These computers will be used for testing not just the software, but the installation process itself. Exclusions win, so computers that are also in an excluded group for the title will not be used as pilots.
 
@@ -486,6 +511,10 @@ module Xolo
 
               When adding a new version, the pilot groups from the previous version will be inherited if you don't specify any. To make the new version have no pilot groups, and fall back to these defined in the title, use '#{Xolo::NONE}'
 
+              Xolos Group Types:
+              - Excluded & Target Groups: affect which computers an see a title & its versions.
+              - Release & Pilot Groups: affect which computers have the title automatically installed or updated, and when. Note, when a version is released all targeted/non-excluded/non-frozen computers with it installed will get the update.
+
               NOTE: Any non-excluded computer can be used for piloting at any time by manually installing the yet-to-be-released version using `sudo xolo install` or `xadm deploy`.  The members of the pilot groups are just the ones that will have it auto-installed.
             ENDDESC
           },
@@ -507,7 +536,7 @@ module Xolo
             readline: :jamf_computer_group_names,
             invalid_msg: 'Invalid release group(s). Must exist in Jamf and not be excluded.',
             desc: <<~ENDDESC
-              One or more Jamf Computer Groups whose members will automatically have this title installed.
+              One or more Jamf Computer Groups whose members will automatically have this title installed if it isn't already.
 
               These groups affect the _initial_ installation of a title when a version is released. Any Mac with the title installed, will get updates (if not excluded) regardless of the release-groups.
 
@@ -519,12 +548,16 @@ module Xolo
 
               To remove all existing, use '#{Xolo::NONE}'.
 
+              Xolos Group Types:
+              - Excluded & Target Groups: affect which computers an see a title & its versions.
+              - Release & Pilot Groups: affect which computers have the title automatically installed or updated, and when.
+
               NOTE: When a version is in 'pilot', before it is released, these groups are ignored, but instead a set of 'pilot' groups is defined for each version - and those groups will have that version auto-installed.
             ENDDESC
           },
 
           # @!attribute excluded_groups
-          #   @return [Array<String>] Jamf groups that are not allowed to install this title
+          #   @return [Array<String>] Jamf groups that are not allowed to install or update this title
           excluded_groups: {
             label: 'Excluded Computer Groups',
             cli: :x,
@@ -536,7 +569,7 @@ module Xolo
             readline: :jamf_computer_group_names,
             invalid_msg: 'Invalid excluded computer group(s). Must exist in Jamf.',
             desc: <<~ENDDESC
-              One or more Jamf Computer Groups whose members are not allowed to install this title.
+              One or more Jamf Computer Groups whose members are not allowed to install this title. Computers that are members cannot see the title's existance.
 
               When a computer is in one of these groups, the title is not available at all, for installation or updates, even if the computer is in a pilot or release group.
 
@@ -544,7 +577,48 @@ module Xolo
 
               To remove all existing, use '#{Xolo::NONE}'.
 
-              NOTE: Regardless of the excluded groups set here, if the server has defined a 'forced_exclusion' in its config, that group is always excluded from all xolo titles. Also, computers that are 'frozen' for a title are excluded.
+              Xolos Group Types:
+              - Excluded & Target Groups: affect which computers an see a title & its versions.
+              - Release & Pilot Groups: affect which computers have the title automatically installed or updated, and when. Note, when a version is released all targeted/non-excluded/non-frozen computers with it installed will get the update.
+
+              Excluding vs Freezing:
+              - Excluded Groups are how to prevent members from accessing titles in Xolo. It can be thought of as 'freezing for groups'
+              - Freezing (via 'xadm freeze...') is how to prevent individual computers from accessing titles in Xolo. It can be thought of as 'exclusion for individual computers'
+
+              NOTE: Regardless of the excluded groups set here, if the server has defined a 'forced_exclusion' in its config, that group is always excluded from all xolo titles.
+
+              See also --target-groups
+            ENDDESC
+          },
+
+          # @!attribute target_groups
+          #   @return [Array<String>] Jamf groups that are exclusively allowed to install or update this title.
+          target_groups: {
+            label: 'Target Computer Groups',
+            cli: :t,
+            validate: true,
+            type: :string,
+            multi: true,
+            changelog: true,
+            readline_prompt: 'Group Name',
+            readline: :jamf_computer_group_names,
+            invalid_msg: 'Invalid target computer group(s). Must exist in Jamf.',
+            desc: <<~ENDDESC
+              One or more Jamf Computer Groups whose members are exclusively allowed to install this title. Computers that are NOT members cannot see the title's existance.
+
+              This is the opposite of --excluded-groups, however if a computer is in both target and excluded groups, the exclusion wins.
+
+              When a computer is not in one of these groups, the title is not available at all, for installation or updates, even if the computer is in a pilot or release group.
+
+              When using the --target-groups CLI option, you can specify more than one group by using the option more than once, or by providing a single option value with the groups separated by commas.
+
+              To remove all existing, use '#{Xolo::NONE}'.
+
+              Xolos Group Types:
+              - Excluded & Target Groups: affect which computers an see a title & its versions.
+              - Release & Pilot Groups: affect which computers have the title automatically installed or updated, and when. Note, when a version is released all targeted/non-excluded/non-frozen computers with it installed will get the update.
+
+              See also --excluded-groups
             ENDDESC
           },
 
@@ -606,7 +680,7 @@ module Xolo
           # @!attribute expiration
           #   @return [Integer] Number of days of disuse before the title is uninstalled.
           expiration: {
-            label: 'Expire Days',
+            label: 'Expiration Days',
             cli: :e,
             validate: true,
             type: :integer,
@@ -659,15 +733,41 @@ module Xolo
             changelog: true,
             walkthru_na: :ssvc_na,
             desc: <<~ENDDESC
-              Make this title available in Self Service. Only the currently released version will be available.
-
-              While in pilot, a version is installed via its auto-install policy,
-              or 'sudo xolo install <title> <version>' or updated via its Patch Policy.
+              Make this title available in Self Service for initial installation. Only the currently released version will be available. (Pilot versions can be installed based on their --pilot-groups or manally via 'xadm deploy' or 'xolo install')
 
-              It will never be available to excluded computers.
+              It will never be available to excluded computers, even via self service.
 
               Self Service is not available for titles with the release_group 'all'.
-              To remove the self-service option, use --no-self-service.
+
+              To explicitly set this to false, use --no-self-service.
+
+              See also --self-service-updates.
+            ENDDESC
+          },
+
+          # @!attribute self_service_updates
+          #   @return [Boolean] Do versions appear in Self Service for updates?
+          self_service_updates: {
+            label: 'Self Service Updates?',
+            cli: :V,
+            type: :boolean,
+            validate: :validate_boolean,
+            default: false,
+            changelog: true,
+            desc: <<~ENDDESC
+              Make versions available in Self Service for updates. This setting is independent of the --self-service setting for initial installs. Unlike that setting, this can be set when the release-group is 'all'.
+
+              By default this is false, Patch Policies for versions will be set to 'Install Automatically'.
+
+              If set to true, Patch Policies for versions will be set to 'Make Available in Self Service' and the version will appear in the Updates section when available. The update won't happen until the user clicks a button, or the 7-day deadline passes. Notifications will be displayed daily.
+
+              When installing automatically, or the deadline passes, the update will happen at the checkin after the next recon. If the version has any KillApps, the user will be prompted to quit them, with a grace period of 15 minutes before the update starts.
+
+              Any Self Service icon uploaded for the title will be used for its versions. If needed, upload one for the title with 'xadm edit-title --self-service-icon /path/to/image/file' (the title itself doesn't need to be in Self Service)
+
+              To explicitly set this to false, use --no-self-service-updates.
+
+              See also --self-service.
             ENDDESC
           },
 
@@ -684,7 +784,7 @@ module Xolo
             invalid_msg: 'Invalid category. Must exist in Jamf Pro.',
             desc: <<~ENDDESC
               The Category in which to display this title in Self Service.
-              REQUIRED if self_service is true, ignored otherwise
+              REQUIRED if --self-service is true, recommended if --self-service-updates is true.
             ENDDESC
           },
 

data/lib/xolo/core/base_classes/version.rb

@@ -273,9 +273,8 @@ module Xolo
             ENDDESC
           },
 
-          # @!attribute jamf_pkg
-          #   @return [String] The file name of the installer for the Jamf Package object that
-          #     installs this version.  'xolo-<title>-<version>.pkg' (or .zip)
+          # @!attribute pkg_to_upload
+          #   @return [String] The path to a local pkg, or 'uploaded'
           pkg_to_upload: {
             label: 'Upload Package',
             type: :string,
@@ -288,9 +287,9 @@ module Xolo
             desc: <<~ENDDESC
               The path to a local copy of the installer package for this version. Will be uploaded to Xolo and then Jamf Pro distribution point(s), replacing any previously uploaded.
 
-              Must be a flat .pkg file, or a .zip compressed old-style bundle package.
+              It must be a flat .pkg file. Old-school zipped bundle-style packages are not supported by Xolo.
 
-              It will be renamed to 'xolo-<title>-<version>.pkg' (or .zip).
+              It will be renamed to 'xolo-<title>-<version>.pkg'.
               If your Xolo server is confiured to sign unsigned packages, it will do so along the way.
 
               Required when creating a new version unless the title is configrued to use autopkg.
@@ -461,7 +460,7 @@ module Xolo
             desc: <<~ENDDESC
               When this version was skipped in Xolo.
               This is when the Xolo sets the status of this version to 'skipped', meaning it was never released in Xolo, and now a newer version has been released.
-              It will be automatically deleted at the next nightly cleanup, unless the server is configured otherwise.
+              It will be automatically deleted at the next nightly maintenance, unless the server is configured otherwise.
             ENDDESC
           },
 

data/lib/xolo/core/exceptions.rb

@@ -39,11 +39,13 @@ module Xolo
 
       class InvalidTokenError < ConnectionError; end
 
+      class TooSoonError < ConnectionError; end
+
       class ServerError < ConnectionError; end
 
       # Parsing errors
 
-      class DisallowedYAMLDumpClass; end
+      class DisallowedYAMLDumpClass < ConnectionError; end
 
     end # module Exceptions
 

data/lib/xolo/core/version.rb

@@ -12,7 +12,7 @@ module Xolo
 
     module Version
 
-      VERSION = '2.0.3'.freeze
+      VERSION = '2.2.0'.freeze
 
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xolo-admin
 version: !ruby/object:Gem::Version
-  version: 2.0.3
+  version: 2.2.0
 platform: ruby
 authors:
 - Chris Lasell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-25 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday