xolo-server 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7749e82011acb35cebb065d60d29c6c94148e27a18d0eb936e206165c578023c
-  data.tar.gz: 732faf4f08115109c815ad866de0029ec46d30da4e44afcf1c4f3b30aaa15dd9
+  metadata.gz: 84bf8381f9806f22096c6404f36e62cb49d418384cf8a9cd722bbb4afbfc60d1
+  data.tar.gz: 22e325e7e124104589c946006531cad9e5ab3b8db047b8403e66d5bb83166d0f
 SHA512:
-  metadata.gz: 3e5d69ac7b0eb7986073bb4415b7779607a84e3fad95425be6cc7e69e144d3b23bfba8d78a631af3077b5f8bf318e1b0a221f19f69c12438542e33108e934aa9
-  data.tar.gz: 1b99190baff9c56375b01c3b1225a8ce8c1dee53173c2e35b985d6a40a91c2b6ab8143bb7300c96e4a74c59036e492252c56dc32e990396730e4a63fe08b69c2
+  metadata.gz: 8dde7e538db3e32619b7828057e7671c8eef1460a60df222f63754624d98093b66b6badf78b8834ef4517343b0464e965471cd1bbb841ec66886b20d5ca98d0a
+  data.tar.gz: 738fdb9b8c7cd66cb82c1efe39cbc00aafa011a0adc6b4936f6a2fcaadf1733f64fa88a2648a8a7d8639d4866203328be8ce8baee86103d9982e83b4cf144841

data/data/client/xolo

@@ -159,11 +159,23 @@ 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.
-    If you are only installing only one specific version of one title, you can
-    omit the =, e.g. install <title> <version>.
+
+    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.

data/data/com.pixar.xoloserver.plist

@@ -10,14 +10,21 @@
   <key>EnvironmentVariables</key>
   <dict>
     <key>GEM_PATH</key>
-    <string></string>
+    <string>/path/to/gems1:/path/to/gems2</string>
     <key>PATH</key>
-    <string></string>
+    <string>/path/to/things1:/path/to/things2</string>
   </dict>
   -->
   <key>ProgramArguments</key>
   <array>
     <string>/usr/local/bin/xoloserver</string>
+    <!-- On production servers, uncomment this line:
+    <string>-p</string>
+    -->
+
+    <!-- to start the server with debug-logging on, uncomment this line:
+    <string>-d</string>
+    -->
   </array>
   <key>RunAtLoad</key>
   <true/>

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.1.0'.freeze
+      VERSION = '2.2.0'.freeze
 
     end
 

data/lib/xolo/server/app.rb

@@ -111,7 +111,7 @@ module Xolo
         Xolo::Server.start_time = Time.now
 
         Xolo::Server::Log.log_rotation_timer_task.execute
-        Xolo::Server::Helpers::Maintenance.cleanup_timer_task.execute
+        Xolo::Server::Helpers::Maintenance.maint_timer_task.execute
 
         # Disable warnings in logs about known scope bug in Jamf Classic API
         Jamf::Scopable::Scope.do_not_warn_about_policy_scope_bugs

data/lib/xolo/server/configuration.rb

@@ -159,7 +159,7 @@ module Xolo
         server_admin_jamf_group: {
           type: :string,
           desc: <<~ENDDESC
-            The name of a Jamf account-group (not a User group) that allows the use of the server admin commands of 'xadm', including --run-server-cleanup,
+            The name of a Jamf account-group (not a User group) that allows the use of the server admin commands of 'xadm', including --run-server-maint,
             --update-client-data, --rotate-server-logs and --set-server-log-level.
 
             Members of this group can also use the xadm commands that require the 'admin_jamf_group' group.
@@ -353,7 +353,7 @@ module Xolo
           default: Xolo::Server::Helpers::Maintenance::DFT_DEPRECATED_LIFETIME_DAYS,
           type: :integer,
           desc: <<~ENDDESC
-            When a version is deprecated, it will be automatically deleted by the nightly cleanup this many days later. If set to 0 or less,
+            When a version is deprecated, it will be automatically deleted by the nightly maintenance this many days later. If set to 0 or less,
             deprecated versions will never be deleted.
 
             Deprecated versions are those that have been released, but a newer version has been released since then.
@@ -369,7 +369,7 @@ module Xolo
           default: false,
           type: :boolean,
           desc: <<~ENDDESC
-            Normally, skipped versions are deleted during nightly cleanup. If you set this to true, skipped versions will be kept.
+            Normally, skipped versions are deleted during nightly maintenance. If you set this to true, skipped versions will be kept.
 
             Skipped versions are those that were never released, but a newer version has been released.
 
@@ -611,7 +611,7 @@ module Xolo
         },
 
         # @!attribute forced_exclusion
-        #   @return [String] The name of a single Jamf Pro computer groups that will ALWAYS be excluded
+        #   @return [String] The name of a single Jamf Pro computer group that will ALWAYS be excluded
         #      and will never see any titles or versions in Xolo.
         forced_exclusion: {
           type: :string,

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

@@ -39,14 +39,14 @@ module Xolo
         # We use routes like this for internal tasks that require a
         # server-request context.
         INTERNAL_ROUTES = [
-          '/maint/cleanup-internal'
+          '/maint/maint-internal'
         ].freeze
 
         # these routes must
         SERVER_ADMIN_ROUTES = [
           '/maint/threads',
           '/maint/state',
-          '/maint/cleanup',
+          '/maint/maint-start',
           '/maint/update-client-data',
           '/maint/rotate-logs',
           '/maint/set-log-level',
@@ -74,7 +74,7 @@ module Xolo
         #
         # This allows the xolo server to send requests to itself without needing
         # to authenticate, as is needed for some kinds of maintenance tasks
-        # such as cleanup.
+        # such as maintenance.
         #
         # The token value is generated anew at startup and is a long random string, it
         # is only available to the xolo server itself from its memory, and