xolo-server 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e78577a11f1d65aba560ec5540c3a79acdfc7d6a491060e256bb9e2da5a057d9
-  data.tar.gz: 9e7e776f48e8e9e260bc41a9090603bbfc41d1dad7dd62fc00396ce9914450cb
+  metadata.gz: 7f515836aab0143c5343395e240de91947be9aef7cc70b266d4e1a84eb5fe714
+  data.tar.gz: 7f438c26d4974cb273241ec6bd72a9521eef562283cea9f64ba5f4521c34cf40
 SHA512:
-  metadata.gz: b83f99bda3666a2fd124241a26882499c393a75b3289fb503bdcb6ac994827228b5f813acc79a7a81f437f879b2e9aaca727800ddd711f17b2713d7a45a98738
-  data.tar.gz: 05bb86ec68010bf2258853983f093936ffa735c52144b6760c64177621a971bdf93823a46562a4b347c5a080d5206900a39ff8b6019e7fb1fa0cf0b400e4336e
+  metadata.gz: 2b2cc84027b9a9af0fc4619d1ba5d564700043207e5ee96be50a69f248b5b4644605b5de569cb9906ec6b71c3d7ee322041bfe4395187cdcce06bcacf9b2d099
+  data.tar.gz: 344224658c124b01d6caa0b175ef64e3e200618335224119efb2d5430a38e178d15bba1878282ee16908c51c9979d5dbadbcd02da8aa293812ac22a1a4d32598

data/data/client/xolo

@@ -97,6 +97,7 @@ be_verbose=
 debugging_on=
 no_versions=
 show_xolo_version=
+do_recon=
 
 # arguments
 command=
@@ -155,7 +156,9 @@ Options:
                      policies, etc, from test xolo server, not the production server.
                      Setting the XOLO_TEST_MODE env. variable does the same thing.
   -r, --recon:       With 'install' or 'uninstall' run a 'jamf recon' after the
-                     operation completes successfully.
+                     operation completes successfully. With 'update', run a 'jamf recon'
+                     before the checkin. NOTE: With update, the whole process may take
+                     many minutes.
   -n, --no-versions: With the 'list-titles' and 'list-installed' commands,
                      do not show the versions available, or the version
                      installed, respectively.
@@ -190,6 +193,9 @@ Commands:
     every time this computer checks in with Jamf Pro.
     Note: this just runs the 'jamf policy' command, which will execute any pending
     Jamf policies triggered by "recurring check-in".
+    If --recon is given, a Jamf recon will run first, followed by a 1 minute pause
+    for Jamf to process the data before doing the check-in. This helps the Mac to see
+    very recently-released versions as patch updates.
 
   refresh, r
     Update xolo's information about current titles and versions.
@@ -1035,6 +1041,12 @@ function run_recon() {
 function update() {
   say "Updating installed titles, or installing newly scoped ones..."
 
+  if [[ -n "$do_recon" ]]  ; then
+    run_recon
+    say "Pausing to let Jamf Pro process recon data..."
+    sleep 60
+  fi
+
   debug "Running jamf policy..."
     if be_verbose ; then
     $JAMF policy -verbose

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

@@ -459,15 +459,17 @@ module Xolo
           },
 
           # @!attribute auto_release_delay
-          #   @return [String] 'none' or an integer in string. How many days before new versions are automatically released?
+          #   @return [String] 'none', 'monthly', 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,
+            validate: true,
             changelog: true,
-            invalid_msg: "Must be a non-negative integer, or '#{Xolo::NONE}'.",
+            invalid_msg: "Must be a non-negative integer, '#{Xolo::MONTHLY}', or '#{Xolo::NONE}'.",
             desc: <<~ENDDESC
               Specify how many days after a new version appears before it is automatically released from pilot.
 
@@ -477,6 +479,8 @@ module Xolo
 
               Setting it to zero means that new versions will be released at the next nightly auto-release task. *** USE WITH EXTREME CAUTION ***
 
+              Setting it to '#{Xolo::MONTHLY}' will release it on whatever day of the month is defined in the Xolo server's 'auto_release_monthly' setting, or on the first day of the month if the server isn't set. The server may be set to a specific date, like '15' or to an ordinal-weekday, like '3rd Mon'.
+
               To unset, meaning versions are never auto-released, use '#{Xolo::NONE}'
 
               Auto-release happens during the server's nightly maintenance between 2-3am.

data/lib/xolo/core/constants.rb

@@ -23,6 +23,9 @@ module Xolo
 
       ERROR = 'ERROR'
 
+      # A possible value for a title's auto-release delay
+      MONTHLY = 'monthly'
+
       # Several things use x
       X = 'x'
 

data/lib/xolo/core/version.rb

@@ -12,7 +12,7 @@ module Xolo
 
     module Version
 
-      VERSION = '2.3.0'.freeze
+      VERSION = '2.5.0'.freeze
 
     end
 

data/lib/xolo/server/configuration.rb

@@ -143,6 +143,25 @@ module Xolo
           ENDDESC
         },
 
+        # @!attribute xadm_authenticator
+        #   @return [String] How to authenticate users of 'xadm', either 'use-jamf' or a path to an authentication tool.
+        xadm_authenticator: {
+          required: true,
+          type: :string,
+          desc: <<~ENDDESC
+            The method for authenticating users of 'xadm'. The value 'use-jamf' will authenticate the user's name and password by trying
+            to connect to the Jamf Pro API. This may not work for Jamf Cloud instances with an identity provider or other more complex
+            authentication processes. There are plans to address this in a future version of xolo.
+
+            Alternatively, provide the full path to a CLI tool installed on the xolo server. This tool must take two lines on its standard-input:
+            the username, then the password. It must return 'OK' to its standard-output, and exit with status 0, for the credentials to be
+            considered correct.
+
+            After authentication, the username provided must be a member of the Jamf account-group defined in 'admin_jamf_group', and/or
+            that defined in 'server_admin_jamf_group'.
+          ENDDESC
+        },
+
         # @!attribute admin_jamf_group
         #   @return [String] The name of a Jamf account-group containing users of 'xadm'
         admin_jamf_group: {
@@ -156,6 +175,7 @@ module Xolo
 
         # @!attribute server_admin_jamf_group
         #   @return [String] The name of a Jamf account-group containing users of 'xadm'
+        #     who are allowed to manage the xoloserver itself
         server_admin_jamf_group: {
           type: :string,
           desc: <<~ENDDESC
@@ -829,6 +849,30 @@ module Xolo
             NOTE: AutoPkg recipes are always run with '-k FAIL_RECIPES_WITHOUT_TRUST_INFO=yes', and will fail if you have not 'trusted'
             them by making an override. See the AutoPkg docs for details.
           ENDDESC
+        },
+
+        # @!attribute auto_release_monthly
+        #   @return [String] Which day of the month should auto-releases happen?
+        auto_release_monthly: {
+          type: :string,
+          desc: <<~ENDDESC
+            If a title has an --auto-release-delay set to '#{Xolo::MONTHLY}', this defines which day of the month the release happens. Releases happen during nightly maintenence, between 2 and 3am, which may affect the value you put here. Monthly releases will only release the newest version, if it's status is 'pilot'.
+
+            Setting this string to an integer will cause the release to happen on that day of the month, so '15' makes it happen on the 15th of the month. If you set the value to beyond the end of the month, it will happen on the last day of the month, so set it to '31' (or higher) for the last day of every month.
+
+            Alternatively you can set it to a string specifying an 'ordinal-weekday', e.g. '2nd Tue', which will cause the release to happen on the second Tuesday of every month.
+
+            Ordinal weekday strings must be two space-separated values: First one of '1st', '2nd', '3rd', '4th', or 'last', then a 3-letter English weekday, one of 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', or 'Sat'.  All of these are case-insensitive.
+
+            Examples: '2nd Sun', '4th Fri', 'Last Wed'
+
+            If a title is set to 'monthly', and the server has no valid value here, releases happen on the first day of every month, regardless of weekday.
+
+            Setting monthly auto-release can help avoid update-fatigue when you have lots of titles auto-releasing frequently. Users can expect all their updates at around the same time once a month.
+
+            Note that new versions of titles can always be manually released at any time once they are added to xolo.
+            So if an important security update comes out and you don't want to wait up to a month to release it, you can do so manually with 'xadm release <title> <version>'
+          ENDDESC
         }
 
       }.freeze

data/lib/xolo/server/helpers/auth.rb

@@ -59,6 +59,9 @@ module Xolo
         # The loopback address for IPV4, aka 'localhost'
         IPV4_LOOPBACK = '127.0.0.1'
 
+        # This is a possible value for xadm_authenticator
+        USE_JAMF = 'use-jamf'
+
         # Module methods
         #####################
         #####################
@@ -239,6 +242,33 @@ module Xolo
           false
         end
 
+        # authenticate via an external xadm authenticator tool.
+        # it must exit with status 0, and send 'OK' to its stdout
+        #
+        # @param admin [String] The jamf acct name of the person seeking access
+        #
+        # @param pw [String] The password for the jamf acct
+        #
+        # @return [Boolean] Did the password work for the user?
+        ####################
+        def authenticated_via_xadm_authenticator?(admin, pw)
+          upw = "#{admin}\n#{pw}"
+          out = nil
+          err = nil
+          success = false
+
+          Open3.popen3(Xolo::Server.config.xadm_authenticator) do |inp, outp, serr, wthr|
+            inp.print upw
+            inp.close
+
+            out = outp.read.chomp
+            err = serr.read.chomp
+            success = wthr.value.success?
+          end
+          log_warn "xadm authenticator failed for admin '#{admin}': #{err} " unless success
+          success && out == Xolo::OK
+        end
+
         # Try to authenticate the jamf user trying to log in to xolo.
         # This must be a regular Jamf user acct, not an API client.
         #

data/lib/xolo/server/helpers/autopkg.rb

@@ -35,6 +35,11 @@ module Xolo
         AUTOPKG_UPLOADED_BY = 'autopkg'
         FAIL_UNTRUSTED_RECIPES_CLI_OPT = '-k FAIL_RECIPES_WITHOUT_TRUST_INFO=yes'
 
+        # when we find a .pkg after a recipe has run, it can't be older than this many
+        # seconds, or we assume it is from some other run of the recipe, not the one we
+        # just did. Currently 20 min
+        MAX_PKG_AGE = 1200
+
         # Module Methods
         #######################
         #######################
@@ -89,12 +94,53 @@ module Xolo
           @autopkg_enabled = false
         end
 
+        # the autopkg report-plist path, based on the
+        # title name & timestamp w/nanosecs
+        # @return [Pathname]
+        ##############################
+        def autopkg_report_plist_path
+          @autopkg_report_plist_path ||= Pathname.new "/tmp/xolo-autopkg-report-#{@title_id_for_autopkg}-#{Time.now.strftime('%s%N')}.plist"
+        end
+
+        # Given a Hash or Array, recursively look for a
+        # Hash Key :version and return the value.
+        # Returns the first such key it finds.
+        #
+        # @param collection [Hash, Array] the data to search
+        #
+        # @return [String, nil] the first 'version' value found, or nil if not found
+        ###########################
+        def find_version(collection)
+          version = nil
+
+          if collection.is_a? Hash
+            collection.each do |key, value|
+              if key == :version
+                version = value
+                break
+              end
+              version = find_version(value) if value.is_a?(Hash) || value.is_a?(Array)
+              break if version
+            end
+          elsif collection.is_a? Array
+            collection.each do |value|
+              version = find_version(value) if value.is_a?(Hash) || value.is_a?(Array)
+              break if version
+            end
+          end # if collection.is_a
+
+          version
+        end # def
+
         # the autopkg run command for this title
         #####################################
         def autopkg_run_command(title_object)
           # is autopkg enabled for the server as a whole?
           return unless autopkg_enabled?
 
+          # is autopkg enabled for this title?
+          return unless title_object.autopkg_enabled?
+
           [
             '/bin/launchctl',
             'asuser',
@@ -106,7 +152,9 @@ module Xolo
             'run',
             '--verbose',
             title_object.autopkg_recipe,
-            FAIL_UNTRUSTED_RECIPES_CLI_OPT
+            FAIL_UNTRUSTED_RECIPES_CLI_OPT,
+            '--report-plist',
+            autopkg_report_plist_path.to_s
           ]
         end
 
@@ -122,33 +170,115 @@ module Xolo
           # is autopkg enabled for this title?
           return unless title_object.autopkg_enabled?
 
+          # Make this available to other methods here
+          @title_id_for_autopkg = title_object.title
+
           recipe = title_object.autopkg_recipe
           pkgdir = Pathname.new title_object.autopkg_dir
           clean_old_pkgs pkgdir
 
           cmd = autopkg_run_command(title_object)
-          progress "Running AutoPkg recipe for #{title_object.title} via command: #{cmd.join(' ')}", log: :info
+          progress "Running AutoPkg recipe '#{recipe}' for #{title_object.title}..."
+          log_info "Running AutoPkg recipe for #{title_object.title} via command: #{cmd.join(' ')}"
 
           unlock_autopkg_user_keychain
-
           souterr, status = Open3.capture2e(*cmd)
           souterr.strip!
 
           if status.success?
-            progress "AutoPkg recipe #{recipe} for title '#{title_object.title}' completed successfully.", log: :info, alert: true
+            msg = "AutoPkg recipe '#{recipe}' for title '#{title_object.title}' completed successfully."
+            progress msg, log: :info, alert: true
+
             log_debug 'AutoPkg output:'
             souterr.lines.each { |l| log_debug "AutoPkg: #{l.chomp}" }
 
             pkgs = pkgdir.children.select { |c| c.extname == '.pkg' }
+            # the Pathname of the newest .pkg
             pkgs.max_by(&:mtime)
 
+          # Failure is a option
           else
-            progress "ERROR: AutoPkg recipe #{recipe} failed with status #{status.exitstatus}.", log: :error, alert: true
-            log_error 'AutoPkg output:'
-            souterr.lines.each { |l| log_error "AutoPkg: #{l.chomp}" }
+            handle_failed_recipe(
+              recipe: recipe,
+              title_object: title_object,
+              status: status,
+              souterr: souterr
+            )
+          end
+        end
+
+        # Deal with a failed recipe run
+        #
+        ###############################
+        def handle_failed_recipe(recipe:, title_object:, status:, souterr:)
+          errmsg = "ERROR: AutoPkg recipe '#{recipe}' for title '#{title_object.title}' failed with status #{status.exitstatus}. Details logged and emailed to '#{title_object.contact_email}'"
+
+          progress errmsg, log: :error, alert: true
 
-            raise "AutoPkg recipe #{recipe} failed."
+          # log the details
+          log_error 'AutoPkg output:'
+          souterr.lines.each { |l| log_error "AutoPkg: #{l.chomp}" }
+
+          # email the details to the contact addr for the title
+          email_subj = "ERROR: AutoPkg recipe FAILED for title '#{title_object.title}'"
+          email_msg = <<~ENDEMAIL
+            The autopkg recipe '#{recipe}' for title '#{title_object.title}' failed with status #{status.exitstatus}.
+
+            Please check that the recipe is up to date. If not, please update the recipe's repo by running this as the autppkg user on the xolo server:
+
+               autopkg repo-update <repo-name>
+
+            Then confirm you still trust the recipe.
+            If so, run:
+
+               autopkg update-trust-info '#{recipe}'
+
+            Then tell xolo the xolo server to re-run the recipe - the .pkg will always be assigned to the latest version.
+
+               xadm rerun-autopkg-recipe #{title_object.title}
+
+            If needed, contact your xoloserver administrator to perform the autopkg commands.
+
+            Here is the output from the failed recipe:
+            ------------------------------------------
+            #{souterr}
+          ENDEMAIL
+
+          send_email to: title_object.contact_email, subject: email_subj, msg: email_msg, html: false
+
+          raise "AutoPkg recipe #{recipe} failed."
+        end
+
+        # confirm a given autopkg package is OK to use after running a recipe
+        ###########################
+        def validate_autopkg_pkg(pkg_src, desired_version)
+          if pkg_src.nil?
+            msg = 'No pkg was found after running the autopkg recipe. Please check the AutoPkg recipe and the server log for details. Make sure the --autopkg-dir is correct. Nothing to upload.'
+            progress msg, log: :warn, alert: true
+            return false
           end
+
+          oldest_allowed = Time.now - MAX_PKG_AGE # 20 minutes ago
+          if pkg_src.mtime < oldest_allowed
+            msg = "A pkg was found after running the autopkg recipe, but it was last modified at #{pkg_src.mtime}, which is more than 20 minutes ago. To avoid accidentally uploading an old pkg, the server will not upload this pkg. Please check the AutoPkg recipe and the server log for details. Nothing to upload"
+            progress msg, log: :warn, alert: true
+            return false
+          end
+
+          fetched_version =
+            if autopkg_report_plist_path.file?
+              json_report = `/usr/bin/plutil -convert json #{autopkg_report_plist_path.pix_shellescape} -o -`
+              report = JSON.parse json_report, symbolize_names: true
+              find_version report[:summary_results]
+            end
+
+          if fetched_version != desired_version
+            msg = "A pkg was found after running the recipe, but the version that was fetched was '#{fetched_version}', and we were expecting version '#{desired_version}'. Nothing to upload"
+            progress msg, log: :warn, alert: true
+            return false
+          end
+
+          true
         end
 
         # remove any existing pkgs from the given autopkg output dir

data/lib/xolo/server/helpers/maintenance.rb

@@ -43,14 +43,15 @@ module Xolo
         # MAINT_CHECK_INTERVAL = 600
 
         # At what hour should the nightly maintenance run?
+        # default to 2am
         MAINT_HOUR = 2
         # MAINT_HOUR = 10
 
-        # Maint won't run unless the last run was at least this many
+        # Automated maint won't run unless the last run was at least this many
         # seconds ago.
         # 23 hrs ago means that even if we check twice within the
         # MAINT_HOUR, only the first one will run.
-        MAINT_MAX_FREQ_SECS = 23 * 3600
+        AUTO_MAINT_MAX_FREQ_SECS = 23 * 3600
 
         # the route we POST to, to start the nightly process.
         TIMED_MAINT_TRIGGER_ROUTE = '/maint/maint-internal'
@@ -145,11 +146,11 @@ module Xolo
           now = Time.now
 
           # only run the maintenance if it's during the MAINT_HOUR
-          # and the last one was more than MAINT_MAX_FREQ_SECS ago
+          # and the last one was more than AUTO_MAINT_MAX_FREQ_SECS ago
           if force
             Xolo::Server.logger.info 'Maint: Starting now due to force'
 
-          elsif now.hour == MAINT_HOUR && (now - last_maint) > MAINT_MAX_FREQ_SECS
+          elsif now.hour == MAINT_HOUR && (now - last_maint) > AUTO_MAINT_MAX_FREQ_SECS
             Xolo::Server.logger.info 'Maint: Starting nightly run now'
 
           else
@@ -295,60 +296,157 @@ module Xolo
           # Loop thru the titles
           title_objects.each do |title_obj|
             title = title_obj.title
+            vobj_to_release = nil
 
-            # nothing to do if its nil or 'none'
+            # nothing to do if auto_release_delay is nil or 'none'
             next if title_obj.auto_release_delay.nil? || title_obj.auto_release_delay == Xolo::NONE
 
             # title must be subscribed and autopkg
-            # (enforced in xadm)
+            # (enforced in xadm also)
             next unless title_obj.subscribed? && !title_obj.autopkg_recipe.pix_empty?
 
-            # title must have a non-negative integer for auto_release_delay,
-            # (number of days to wait before release)
-            # could be zero. (enforced in xadm)
-            # NOTE: it is stored as a string because it might be 'none'
-            # TODO: store none as nil, so we don't have to do the pix_integer check??
-            delay = title_obj.auto_release_delay.to_i
-            next unless title_obj.auto_release_delay&.pix_integer? && !delay.negative?
-
-            # Any version with this creation date should be released now, skip if not
-            # So if the auto_release_delay is 7, its today - 7 days.
-            # if the auto_release_delay is 0, its today - 0 days, aka today
-            creation_date_to_be_released_today = today - delay
-
-            # Find the newest pilot version whose creation date is
-            # creation_date_to_be_released_today or earlier
-            # That one should be released now.
-            vobj_to_release = nil
-
-            # version objects are in order of newest to oldest
-            title_obj.version_objects.each do |vobj|
-              next unless vobj.pilot?
-              next unless vobj.creation_date.to_date <= creation_date_to_be_released_today
+            # if the title is set for monthly release, is today the
+            # right day of the month?
+            if title_obj.auto_release_delay == Xolo::MONTHLY
+              unless monthly_release_today?
+                log_debug "Title '#{title}' is set to monthly, but today isn't '#{Xolo::Server.config.auto_release_monthly}'"
+                next
+              end
+
+              # For Monthlies, we only ever auto-release the newest version,
+              # and only if it is in pilot
+              latest_vobj = title_obj.version_objects.first
+              unless latest_vobj&.pilot?
+                log_debug "Title '#{title}' is set to monthly, but the latest version isn't in pilot"
+                next
+              end
+
+              vobj_to_release = latest_vobj
+
+            # Look for a version to be released today.
+            # The delay value must be a non-negative integer
+            elsif title_obj.auto_release_delay.pix_integer?
+              delay = title_obj.auto_release_delay.to_i
+              if delay.negative?
+                log_debug "Title '#{title}': invalid auto_release_delay: #{delay}"
+                next
+              end
+
+              # Given the title's delay, what creation date means
+              # we should release today?
+              # So if the auto_release_delay is 7, its today - 7 days.
+              # if the auto_release_delay is 0, its today - 0 days, aka today
+              creation_date_to_be_released_today = today - delay
+
+              # Find the newest pilot version whose creation date is
+              # creation_date_to_be_released_today or earlier
+              # That one should be released now.
+              # version_objects are in order of newest to oldest
+              title_obj.version_objects.each do |vobj|
+                # gotta be in pilot
+                next unless vobj.pilot?
+
+                # creation date has to be appropriate
+                next unless vobj.creation_date.to_date <= creation_date_to_be_released_today
+
+                vobj_to_release = vobj
+                break
+              end # title_obj.version_objects.each
+            end # if title_obj.auto_release_delay == Xolo::MONTHLY
 
-              vobj_to_release = vobj
-              break
+            # no versions to release today
+            unless vobj_to_release
+              log_debug "Title '#{title}': nothing to auto-release"
+              next
             end
 
-            # no versions to release today
-            next unless vobj_to_release
+            # must have a jamf pkg file uploaded
+            # (won't if autopkg recipe failed)
+            next if vobj_to_release.jamf_pkg_file.pix_empty?
 
             # release it
-            log_debug "Maint: About to auto-release version '#{vobj_to_release.version}' of '#{title}' which came out #{vobj_to_release.creation_date}"
+            log_debug "Maint: About to auto-release '#{title}' version '#{vobj_to_release.version}' which came out #{vobj_to_release.creation_date}"
 
-            # releasing a version is done via the title obj, since it affects the status
-            # of all versions.
+            # releasing a version is done via the title obj,
+            # since it affects the status of all versions.
             title_obj.release vobj_to_release.version
 
-            log_info "Maint: Auto-released version '#{vobj_to_release.version}' of '#{title}' which came out #{vobj_to_release.creation_date}", alert: true
+            log_info "Maint: Auto-released '#{title}' version '#{vobj_to_release.version}' which came out #{vobj_to_release.creation_date}", alert: true
 
             # pause for server to catch up
-            sleep 60
-          end # each title
+            sleep 30
+          end # title_objects.each do |title_obj|
 
           log_debug 'Maint: Done auto-releasing'
         end
 
+        # Is today the day for a monthly release?
+        # The order we check:
+        # - If the server is set to an ordinal weekday, like '3rd Thu'
+        # - If the server is set to the last weekday, like 'Last Thu'
+        # - If the server is set to a specific day of the month, which may be beyond the last day
+        # - All other cases, the first of the month.
+        #
+        # @return [Boolean] is today the day for a monthly release?
+        #################################
+        def monthly_release_today?
+          return @monthly_release_today if defined? @monthly_release_today
+
+          today = Date.today
+          last_day_of_this_month = Date.new(today.year, today.month, -1)
+
+          # downcased string...
+          server_setting = Xolo::Server.config.auto_release_monthly.to_s.downcase
+
+          @monthly_release_today =
+            # matches, e.g. '2nd Mon'
+            ##########
+            if today.to_time.pix_ordinal_weekday.casecmp? server_setting
+              true
+
+            # matches 'last <wkday>' e.g. 'last mon'
+            ##########
+            elsif server_setting.start_with? 'last '
+              # e.g. 'Mmon'
+              release_weekday = server_setting.split(' ').last
+
+              # is it the right weekday?
+              if today.strftime('%a').casecmp? release_weekday
+                # yes... so is it the last one? Make a Range and see it today is in it.
+                last_week_of_the_month = (last_day_of_this_month - 6)..last_day_of_month
+                last_week_of_the_month.include? today
+
+              # it is not the right weekday
+              else
+                false
+              end
+
+            # matches an integer day of the month, or the last day of the month
+            # if server_setting is greater than the number of days in the month
+            ##########
+            elsif server_setting.pix_integer? && server_setting.to_i.positive?
+              # convert string to integer
+              server_setting = server_setting.to_i
+
+              # integer for the last day of the month
+              last_day = last_day_of_this_month.day
+
+              # use the last day of this month if the server is set beyond it
+              server_setting = last_day if server_setting >= last_day
+
+              # is it today?
+              server_setting == today.day
+
+            # All other cases, e.g. bad value or unset on the server,
+            # ... the first of the month.
+            ##########
+            else
+              today.day == 1
+            end
+
+          @monthly_release_today
+        end
+
         # Cleanup versions.
         # @return [void]
         ################################

data/lib/xolo/server/helpers/subscriptions.rb

@@ -91,7 +91,7 @@ module Xolo
                 new_version: new_version
               )
             else
-              log_debug "Title '#{title_name}' ID #{title_id} is not a subscribed title. Ignoring webhook."
+              log_debug "Title '#{title_name}' ID #{title_id} is not a subscribed title on this Xolo server. Ignoring webhook."
             end
           rescue => e
             msg = "Error processing PatchSoftwareTitleUpdated webhook event: #{e.class}: #{e}"
@@ -101,6 +101,39 @@ module Xolo
           end # thread
         end
 
+        # Manually re-trigger a the latest version,
+        # if the subscription update failed.
+        #
+        # Will delete and re-create the latest version, which
+        # must be pilot or pending.
+        def rerun_subscription_update(title)
+          log_debug "Re-running subscription update for latest version of #{title}"
+
+          title_obj = instantiate_title title
+          raise Xolo::UnsupportedError, "Title #{title} is not a subscribed title." unless title_obj.subscribed?
+
+          version = title_obj.latest_version
+          vobj = instantiate_version title: title, version: version
+          unless %w[pilot pending].include? vobj.status
+            raise Xolo::UnsupportedError,
+                  "Latest version must be 'pending' or 'pilot' to rerun subscription updates. Version '#{version}' of title '#{title}' is '#{vobj.status}' "
+          end
+
+          title_obj.log_change msg: "Re-running subscription update for latest version' #{version}'"
+
+          progress "Deleting existing version '#{version}'...", log: :info
+          vobj.delete
+          progress 'Pausing for package deletion (sorry for delay)...'
+
+          sleep 60
+
+          progress "Re-adding version '#{version}' via subscription...", log: :info
+          Xolo::Server::Version.add_version_via_subscription(
+            title_object: title_obj,
+            new_version: version
+          )
+        end
+
       end # Subscriptions
 
     end # Helpers

data/lib/xolo/server/mixins/title_jamf_access.rb

@@ -156,7 +156,6 @@ module Xolo
 
           update_description_in_jamf
           update_ssvc
-          # TODO: deal with icon changes: if changes_for_update&.key? :self_service_icon
 
           # are there any versions yet? if no, not active
           if jamf_title_active?
@@ -234,6 +233,7 @@ module Xolo
 
             vers_obj.update_jamf_package_notes(ttl_obj: self) if need_to_update_description?
             vers_obj.update_patch_policy_deployment(ttl_obj: self) if changes_for_update&.key? :self_service_updates
+            vers_obj.set_patch_policy_ssvc_icon if self_service_updates?
           end
         end
 
@@ -1808,6 +1808,8 @@ module Xolo
           pol.self_service_description = new_desc
 
           pol.self_service_install_button_text = Xolo::Server::Title::SELF_SERVICE_INSTALL_BTN_TEXT
+          pol.self_service_reinstall_button_text = Xolo::Server::Title::SELF_SERVICE_REINSTALL_BTN_TEXT
+
           # icon already uploaded to jamf
           return if ssvc_icon_id
 
@@ -1823,13 +1825,6 @@ module Xolo
           self.ssvc_icon_id = Jamf::Policy.fetch(id: pol.id, cnx: jamf_cnx).icon.id
         end
 
-        # run the autopkg recipe if defined
-        # See Helpers::AutoPkg for more details
-        ############################
-        def run_autopkg_recipe
-          server_app_instance.run_autopkg_recipe self
-        end
-
         # Methods used by subscription stuff
         ##############################
 

data/lib/xolo/server/mixins/version_jamf_access.rb

@@ -454,7 +454,7 @@ module Xolo
           msg = "Jamf: Starting deletion of Package '#{jamf_pkg_name}' id #{jamf_pkg_id} at #{Time.now.strftime '%F %T'}"
           progress msg, log: :info
 
-          warning = "IMPORTANT: Package deletion can be slow. If you plan to re-add this version, '#{version}', please\nwait at least 5 minutes before doing so."
+          warning = "IMPORTANT: Package deletion can be slow. If you plan to re-add this version, '#{version}', please wait a few minutes before doing so."
           progress warning
 
           self.class.pkg_deletion_pool.post do
@@ -978,7 +978,8 @@ module Xolo
         #
         # @param ttl_obj [Xolo::Server::Title] the title object that is being changed.
         ###############################
-        def update_patch_policy_deployment(ttl_obj:)
+        def update_patch_policy_deployment(ttl_obj: nil)
+          ttl_obj ||= title_object
           return unless ttl_obj.changes_for_update[:self_service_updates]
 
           ppol = jamf_patch_policy
@@ -1033,6 +1034,7 @@ module Xolo
             ppol.self_service_reminder_frequency = PATCH_POL_SSVC_REMINDER_FREQ_HRS
             ppol.deadline = PATCH_POL_SSVC_DEADLINE_DAYS
 
+            set_patch_policy_ssvc_icon ppol
           # Automatic deployment
           else
             progress "Jamf: Configuring Patch Policy for version '#{version}' of title '#{title}' for automatic deployment", log: :info
@@ -1052,23 +1054,27 @@ module Xolo
         # @param icon_id [Integer, String] The id of the existing icon to use.
         # @return [Void]
         ##########################
-        def set_patch_policy_ssvc_icon(ppol)
+        def set_patch_policy_ssvc_icon(ppol = nil)
           return unless use_ssvc_updates?
 
+          ppol ||= jamf_patch_policy
+
           if title_object.ssvc_icon_id
             icon_id = title_object.ssvc_icon_id
             log_debug "Jamf: ssvc_icon_id from title object is: #{icon_id}"
           else
             icon_id = title_object.jamf_manual_install_released_policy.self_service_icon.id
             log_debug "Jamf: ssvc_icon_id from manual install policy is: #{icon_id}"
-
+            title_object.ssvc_icon_id = icon_id
           end
 
           if icon_id.pix_empty?
-            log_debug 'Jamf: could not find ssvc icon id, not setting icon for patch policy.'
+            progress "Jamf: could not find ssvc icon id for title '#{title}', not setting icon for patch policy of version '#{version}'.", log: :info
             return
           end
 
+          progress "Jamf: Setting icon for Self Service Updates of version '#{version}' of title '#{title}'", log: :info
+
           # this str can't be frozen for now
           icon_xml = +<<~ENDXML
             <?xml version="1.0" encoding="UTF-8"?>
@@ -1081,12 +1087,14 @@ module Xolo
             </patch_policy>
           ENDXML
 
-          log_debug "Jamf: Adding existing SSvc icon to patch policy for version '#{version}' of title '#{title}'"
+          log_debug "Jamf: Adding existing SSvc icon id '#{icon_id}' to patch policy '#{ppol.id}' for version '#{version}' of title '#{title}'"
 
           # TODO: in ruby-jss, update c_put and related methods to
           # use unfrozen dups of strings for #gsub
 
           jamf_cnx.c_put "patchpolicies/id/#{ppol.id}", icon_xml
+        rescue Jamf::NoSuchItemError => e
+          log_error "Couldn't set SSvc icon id '#{icon_id}' to patch policy '#{ppol.id}' for version '#{version}' of title '#{title}': Jamf::NoSuchItemError: #{e}"
         end
 
         # @return [String] the URL for the Jamf Pro Patch Policy that updates to this version

data/lib/xolo/server/routes/auth.rb

@@ -42,9 +42,12 @@ module Xolo
           pw = payload[:password]
 
           err =
-            if !member_of_admin_jamf_group?(admin)
-              "'#{admin}' is not allowed to use the Xolo server"
-            elsif !authenticated_via_jamf?(admin, pw)
+            ("'#{admin}' is not allowed to use the Xolo server" unless member_of_admin_jamf_group?(admin))
+
+          err ||=
+            if Xolo::Server.config.xadm_authenticator == Xolo::Server::Helpers::Auth::USE_JAMF
+              "Incorrect xolo admin username or password for '#{admin}'" unless authenticated_via_jamf?(admin, pw)
+            elsif !authenticated_via_xadm_authenticator?(admin, pw)
               "Incorrect xolo admin username or password for '#{admin}'"
             end
 

data/lib/xolo/server/routes/subscriptions.rb

@@ -117,6 +117,21 @@ module Xolo
           body resp
         end
 
+        # Manually re-trigger a previous, failed subscription update
+        # Will delete and re-create the existing version, which
+        # must be pilot or pending.
+        ###############
+        post '/titles/:title/rerun-subscription' do
+          title = params[:title]
+
+          halt_on_missing_title title
+          halt_on_locked_title title
+
+          with_streaming do
+            rerun_subscription_update(title)
+          end
+        end
+
       end # Module
 
     end #  Routes

data/lib/xolo/server/routes/titles.rb

@@ -288,6 +288,30 @@ module Xolo
           body data
         end
 
+        # rerun the titles autopkg recipe
+        ######################
+        post '/titles/:title/rerun_autopkg_recipe' do
+          halt_on_missing_title params[:title]
+          halt_on_locked_title params[:title]
+          title = instantiate_title params[:title]
+
+          unless title.autopkg_enabled?
+            msg = "Title '#{params[:title]}' is not configured to use AutoPkg"
+            log_debug "ERROR: #{msg}"
+            halt 409, { status: 409, error: msg }
+          end
+
+          unless title.latest_version
+            msg = "Title '#{params[:title]}' has no versions, cannot re-run the recipe"
+            log_debug "ERROR: #{msg}"
+            halt 404, { status: 404, error: msg }
+          end
+
+          with_streaming do
+            title.rerun_autopkg_recipe
+          end
+        end
+
       end # Titles
 
     end #  Routes

data/lib/xolo/server/title.rb

@@ -120,6 +120,7 @@ module Xolo
       JPAPI_PATCH_REPORT_RSRC = 'patch-report'
 
       SELF_SERVICE_INSTALL_BTN_TEXT = 'Install'
+      SELF_SERVICE_REINSTALL_BTN_TEXT = 'Re-Install'
 
       # Class Methods
       ######################
@@ -490,7 +491,8 @@ module Xolo
       # @return [Pathname] The the local file containing the self-service icon
       #####################
       def ssvc_icon_file
-        @ssvc_icon_file ||= self.class.ssvc_icon_file title
+        # dont cache this, read it every time
+        self.class.ssvc_icon_file title
       end
 
       # @return [Pathname] The the local file containing the code of the version script
@@ -984,16 +986,23 @@ module Xolo
       # @return [void]
       ######################################
       def validate_release(version_to_release)
+        # already released
         if released_version == version_to_release
           raise Xolo::InvalidDataError,
                 "Version '#{version_to_release}' of title '#{title}' is already released"
         end
 
+        # no such version
         unless versions.include? version_to_release
           raise Xolo::NoSuchItemError,
                 "No version '#{version_to_release}' for title '#{title}'"
         end
 
+        # missing .pkg file
+        vobj = version_object version_to_release
+        raise Xolo::MissingDataError, "Version '#{version_to_release}' of title '#{title}' has no uploaded .pkg" if vobj.jamf_pkg_file.pix_empty?
+
+        # visible to jamf?
         jamf_patch_title(refresh: true)
         return if jamf_patch_title.versions.key?(version_to_release)
 
@@ -1144,6 +1153,29 @@ module Xolo
         unlock
       end
 
+      # run the autopkg recipe if defined
+      # See Helpers::AutoPkg for more details
+      ############################
+      def run_autopkg_recipe
+        server_app_instance.run_autopkg_recipe self
+      end
+
+      # Re run the autopkg recipe
+      # and re-upload the pkg
+      ############################
+      def rerun_autopkg_recipe
+        log_change msg: "Re-running autopkg recipe '#{autopkg_recipe}' for latest version '#{latest_version}'"
+
+        pkg_src = server_app_instance.run_autopkg_recipe self
+
+        return unless server_app_instance.validate_autopkg_pkg pkg_src, latest_version
+
+        latest_version_obj = version_object latest_version
+        latest_version_obj.pkg_is_from_autopkg = true
+
+        server_app_instance.process_and_upload_autopkg_pkg title, latest_version_obj, pkg_src
+      end
+
       # Is this title locked for updates?
       #############################
       def locked?

data/lib/xolo/server/version.rb

@@ -307,8 +307,22 @@ module Xolo
 
           auto_release_delay = title_object.auto_release_delay.to_i
 
-          # is auto_release_delay an integer?
-          if title_object.auto_release_delay&.pix_integer? && !auto_release_delay.negative?
+          # is auto_release_delay monthly?
+          if title_object.auto_release_delay == Xolo::MONTHLY
+            monthly = Xolo::Server.config.auto_release_monthly
+            day =
+              if monthly.pix_integer?
+                monthly.to_i.pix_ordinalize
+              elsif %w[sun mon tue wed thu fri sat].include? monthly[-3..-1].downcase
+                monthly
+              else
+                '1st'
+              end
+
+            msg = "New pilot for subscribed title '#{title}', version '#{new_version}' has been created in Xolo via subscription.\nIt will be released during nightly maintenance on the next #{day} of the month"
+
+            # is auto_release_delay an integer?
+          elsif title_object.auto_release_delay&.pix_integer? && !auto_release_delay.negative?
             how_soon =
               if auto_release_delay.zero?
                 'tonight'
@@ -696,8 +710,12 @@ module Xolo
         progress 'Saving version data to Xolo server'
         save_local_data
 
-        create_patch_in_ted unless subscribed?
+        # prepend our version to the version_order array of the title once
+        # our version data has been saved at least once.
+        progress "Updating title version_order, prepending '#{version}'", log: :info
+        title_object.prepend_version(version)
 
+        create_patch_in_ted unless subscribed?
         create_in_jamf
 
         self.status = STATUS_PILOT
@@ -706,10 +724,6 @@ module Xolo
         # add some data
         save_local_data
 
-        # prepend our version to the version_order array of the title
-        progress "Updating title version_order, prepending '#{version}'", log: :info
-        title_object.prepend_version(version)
-
         log_change msg: 'Version Created'
 
         progress "Version '#{version}' of Title '#{title}' has been created in Xolo.", log: :info
@@ -748,18 +762,7 @@ module Xolo
 
         pkg_src = title_object.run_autopkg_recipe
 
-        if pkg_src.nil?
-          msg = 'AutoPkg recipe is enabled for this title, but no pkg was found after running the recipe. Please check the AutoPkg recipe and the server log for details.'
-          progress msg, log: :warn, alert: true
-          return
-        end
-
-        oldest_allowed = Time.now - 1200 # 20 minutes ago
-        if pkg_src.mtime < oldest_allowed
-          msg = "AutoPkg recipe is enabled for this title, and a pkg was found after running the recipe, but it was last modified at #{pkg_src.mtime}, which is more than 20 minutes ago. To avoid accidentally uploading an old pkg, the server will not upload this pkg. Please check the AutoPkg recipe and the server log for details."
-          progress msg, log: :warn, alert: true
-          return
-        end
+        return unless server_app_instance.validate_autopkg_pkg pkg_src, version
 
         # this lets future code know that the pkg we're working with came from autopkg
         self.pkg_is_from_autopkg = true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: xolo-server
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.0
 platform: ruby
 authors:
 - Chris Lasell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday