xolo-server 1.0.1 → 2.0.3

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

@@ -74,6 +74,10 @@ module Xolo
         # - immutable: [Boolean] This value can only be set when creatimg a new title.
         #   When editing an existing title, it cannot be changed.
         #
+        # - title_type: [Symbol, nil] If set to :managed or :subscribed, this option
+        #   is required, and only available, when the title is of that type. If nil or not set,
+        #   the option is available for all title types.
+        #
         # - cli: [Symbol, false] What is the 'short' option flag for this option?
         #   The long option flag is the key, preceded with '--' and with underscores
         #   changed to '-', so display_name is set using the cli option '--display-name'.
@@ -146,6 +150,12 @@ module Xolo
         # - read_only: [Boolean] defaults to false. When true, the server maintains this value, and
         #   its only readable via xadm.
         #
+        # - add_only: [Boolean] This option is only used when creating a new title, it is not
+        #   available when editing an existing title.
+        #
+        # - edit_only: [Boolean] This option is only used when editing an existing title, it is not
+        #   available when creating a new title.
+        #
         # - hide_from_info: [Boolean] when true, do not show this attribute in the 'info' xadm output
         #   NOTE: it will still be available when --json is given with the info command.
         #
@@ -172,20 +182,40 @@ module Xolo
             ENDDESC
           },
 
-          # @!attribute display_name
-          #   @return [String] The display-name for this title
-          display_name: {
-            label: 'Display Name',
-            ted_attribute: :name,
-            required: true,
-            cli: :n,
-            type: :string,
-            validate: :validate_title_display_name,
-            invalid_msg: 'Not a valid display name, must be at least three characters long.',
+          # @!attribute subscribed
+          #   @return [Boolean] is this title subscribed via a Jamf Patch Source?
+          subscribed: {
+            label: 'Subscribed?',
+            cli: :B,
+            type: :boolean,
+            immutable: true,
+            add_only: true,
+            validate: :validate_boolean,
+            default: false,
             changelog: true,
             desc: <<~ENDDESC
-              A human-friendly name for the Software Title, e.g. 'Google Chrome', or 'NFS Menubar'.
-              Must be at least three characters long.
+              Is this title subscribed via a Jamf Patch Source? If not, it is managed by Xolo. By default titles are managed. Once created, titles cannot be changed between managed and subscribed.
+
+              Managed titles have their entire definition, versions and updates managed by Xolo; xadm is used to provide basic details about the title, such as a the display name, publisher, the mechanism by which Jamf Pro knows which version is installed on a Mac. Versions of managed titles are also added and maintained via xadm, setting values such as killapps, OS restrictions, and so on.
+
+              Subscribed titles and their version definitions are maintained by a Patch Source configrued in Jamf Pro. The source defines some aspects of the title and its versions, including the display name, publisher, and mechanism for determining installed versions. New versions are also managed by the Patch Source, including killapps, OS restrictions, and other settings. When they appear, Xolo will at least inform someone (notify the contact email) that a new version is available and needs a .pkg, but can also use autopkg to automatically fetch .pkgs and add new versions for piloting.
+
+              When a title is subscribed, these options are required:
+              --patch-source
+              --title-id
+
+              and these are not available, since the patch source manages them:
+              --display-name
+              --publisher
+              --app-name
+              --app-bundle-id
+              --version-script
+
+              When a subscribed title is added, a Xolo Version is automatically added for the most recent version available from the Patch Source.
+
+              Once created as subscribed or managed, a title cannot be changed to the other type. If you need to change the type, you must delete and re-create the title. Also once created, the patch source and title id for a subscribed title cannot be changed.
+
+              In all cases, a .pkg must be provided for each version known to Xolo, either by uploading it via xadm or configuring the server and the title to use AutoPkg to acquire it.
             ENDDESC
           },
 
@@ -202,12 +232,12 @@ module Xolo
             invalid_msg: <<~ENDINV,
               Not a valid description, must be at least #{MIN_TITLE_DESC_LENGTH} characters.
 
-              Provide a useful dscription of what the software does, URLs, developer names, etc.
+              Provide a useful dscription of what the software does, why it's in Xolo, URLs, developer names, etc.
 
               DO NOT USE, e.g. 'Installs Some App', because we know that already and it isn't helpful.
             ENDINV
             desc: <<~ENDDESC
-              A useful dscription of what the software installed by this title does. You can also include URLs, developer names, support info, etc.
+              A useful dscription of what the software installed by this title does or why it's in Xolo. You can also include URLs, developer names, support info, etc.
 
               DO NOT use, e.g. 'Installs Some App', because we know that already and it isn't helpful.
 
@@ -217,19 +247,44 @@ module Xolo
             ENDDESC
           },
 
+          # @!attribute display_name
+          #   @return [String] The display-name for this title
+          display_name: {
+            label: 'Display Name',
+            ted_attribute: :name,
+            title_type: Xolo::MANAGED,
+            # required: true, # only required if not subscribed
+            cli: :n,
+            type: :string,
+            validate: :validate_title_display_name,
+            walkthru_na: :display_name_na,
+            invalid_msg: 'Not a valid display name, must be at least three characters long.',
+            changelog: true,
+            desc: <<~ENDDESC
+              A human-friendly name for the Software Title, e.g. 'Google Chrome', or 'NFS Menubar'.
+              Must be at least three characters long.
+
+              Cannot be used for subscribed titles, since the Patch Source defines the display name for those.
+            ENDDESC
+          },
+
           # @!attribute publisher
           #   @return [String] The entity that publishes this title
           publisher: {
             label: 'Publisher',
             ted_attribute: :publisher,
-            required: true,
+            # required: true, # only required if not subscribed
+            title_type: Xolo::MANAGED,
             cli: :P,
             type: :string,
+            walkthru_na: :publisher_na,
             validate: true,
             changelog: true,
             invalid_msg: '"Not a valid Publisher, must be at least three characters.',
             desc: <<~ENDDESC
               The company or entity that publishes this title, e.g. 'Apple, Inc.' or 'Pixar Animation Studios'.
+
+              Cannot be used for subscribed titles, since the Patch Source defines the publisher for those.
             ENDDESC
           },
 
@@ -238,6 +293,7 @@ module Xolo
           app_name: {
             label: 'App Name',
             ted_attribute: :appName,
+            title_type: Xolo::MANAGED,
             cli: :a,
             validate: true,
             type: :string,
@@ -251,6 +307,8 @@ module Xolo
 
               If the title does not install a .app bundle, leave this blank, and provide a --version-script.
 
+              Cannot be used for subscribed titles, since the Patch Source defines the app name for those.
+
               REQUIRED if --app-bundle-id is used.
             ENDDESC
           },
@@ -260,6 +318,7 @@ module Xolo
           app_bundle_id: {
             label: 'App Bundle ID',
             ted_attribute: :bundleId,
+            title_type: Xolo::MANAGED,
             cli: :b,
             validate: true,
             type: :string,
@@ -273,6 +332,8 @@ module Xolo
 
               If the title does not install a .app bundle, or if the .app doesn't provide its version via the bundle id (e.g. Firefox) leave this blank, and provide a --version-script.
 
+              Cannot be used for subscribed titles, since the Patch Source defines the bundle ID for those.
+
               REQUIRED if --app-name is used.
             ENDDESC
           },
@@ -282,6 +343,7 @@ module Xolo
           #      title on a client mac
           version_script: {
             label: 'Version Script',
+            title_type: Xolo::MANAGED,
             cli: :v,
             # while the script is stored in the Title Editor as the extension attribute
             # its handled differently, so we don't specify a ted_attribute here.
@@ -299,7 +361,132 @@ module Xolo
               and if no version of the title is installed, it should output:
                  <result></result>
 
-              NOTE: This cannot be used if --app-name & --app-bundle-id are used, but must be used if they are not
+              Cannot be used for subscribed titles, since the Patch Source defines the version script for those.
+
+              REQUIRED unless --app-name and --app-bundle-id are used.
+            ENDDESC
+          },
+
+          # @!attribute patch_source
+          #   @return [String] The name of the Jamf Patch Source that provides this title via subscription
+          patch_source: {
+            label: 'Subscription Patch Source',
+            title_type: Xolo::SUBSCRIBED,
+            cli: :S,
+            type: :string,
+            immutable: true,
+            validate: true,
+            add_only: true,
+            walkthru_na: :patch_source_na,
+            readline: :jamf_patch_sources_with_available_titles,
+            invalid_msg: 'Invalid Patch Source. Unknown Patch Source Name, or it has no available titles.',
+            desc: <<~ENDDESC
+              The name of the Jamf Patch Source that provides this title via subscription.
+
+              This value and --title-id are required for 'subscribed' titles.
+
+              To see a list of titles available for subscription, with their Patch Sources and IDs, use `xadm list-available`.
+
+              Can only be used when adding a new title, not when editing an existing one.
+            ENDDESC
+
+          },
+
+          # @!attribute title_id
+          #   @return [String] The TitleID of the title on the specified Patch Source
+          title_id: {
+            label: 'Subscription Title ID',
+            title_type: Xolo::SUBSCRIBED,
+            cli: :T,
+            type: :string,
+            immutable: true,
+            add_only: true,
+            walkthru_na: :title_id_na,
+            validate: true,
+            invalid_msg: 'Invalid Title ID. Not available in any Patch Source.',
+            desc: <<~ENDDESC
+              The TitleID of the title on the specified Patch Source.
+
+              This is the unique identifier for each title on a patch source, it is a sometimes-meaningless string of alphanumeric characters.
+
+              To find the TitleID of a title available for subscription, use `xadm list-available`
+
+              Can only be used when adding a new title, not when editing an existing one.
+            ENDDESC
+
+          },
+
+          # TODO: Add validation?
+          # @!attribute autopkg_recipe
+          #   @return [String] The autopkg recipe to run when new versions are added to this title
+          autopkg_recipe: {
+            label: 'AutoPkg Recipe',
+            cli: :R,
+            validate: false,
+            type: :string,
+            changelog: true,
+            invalid_msg: "Unknown autopkg recipe. Use one that is configured on the server,  or '#{Xolo::NONE}'.",
+            desc: <<~ENDDESC
+              The name of an autopkg recipe to run when a new version is added to this title. It is expected that the version being added is the latest available and will match the .pkg acquired by a run of the recipe.
+
+              AutoPkg, and the recipe, must be installed and configured on the xoloserver host.
+
+              When using this, --autopkg-dir must also be provided
+
+              To unset, use '#{Xolo::NONE}'
+            ENDDESC
+          },
+
+          # TODO: Add validation?
+          # @!attribute autopkg_dir
+          #   @return [String] The path containg the .pkg acquired by the --autopkg-recipe
+          autopkg_dir: {
+            label: 'AutoPkg Output Directory',
+            cli: :D,
+            validate: false,
+            type: :string,
+            changelog: true,
+            invalid_msg: "Must be an absolute path starting with / and containing at least one more /,  or '#{Xolo::NONE}'.",
+            desc: <<~ENDDESC
+              The path to the directory where the --autopkg-recipe will store the acquired .pkg.
+
+              After running the recipe, xoloserver will look for the newest .pkg file in this directory and upload it to the Jamf distribution servers, as with any other pkg.
+
+              Required when using --autopkg-recipe
+
+              To unset, use '#{Xolo::NONE}'
+            ENDDESC
+          },
+
+          # @!attribute pilot_groups
+          #   @return [Array<String>] Jamf groups that will automatically get new versions installed or
+          #     updated when added, for piloting
+          pilot_groups: {
+            label: 'Pilot Computer Groups',
+            cli: :p,
+            validate: true,
+            type: :string,
+            multi: true,
+            changelog: true,
+            readline_prompt: 'Group Name',
+            readline: :jamf_computer_group_names,
+            invalid_msg: "Invalid group. Must be an existing Jamf Computer Group, or '#{Xolo::NONE}'.",
+            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 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.
+
+              Pilot groups can also be defined per version, in which case these will be ignored. Defining them in the title is useful for subscribed titles, where new versions are created automatically.
+
+              When a version is released, the computers in the release_groups defined in the title will automatically have this version installed - and any non-frozen computers with an older version will have it updated.
+
+              When using the --pilot-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.
+
+              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}'
+
+              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
           },
 
@@ -320,7 +507,9 @@ 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 when new versions are released.
+              One or more Jamf Computer Groups whose members will automatically have this title installed.
+
+              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.
 
               If your Xolo administrators allow it, you can use '#{Xolo::TARGET_ALL}' to auto-install on all computers that aren't excluded. If not, you'll be told how to request setting release groups to '#{Xolo::TARGET_ALL}'.
 
@@ -349,7 +538,7 @@ module Xolo
             desc: <<~ENDDESC
               One or more Jamf Computer Groups whose members are not allowed to install this title.
 
-              When a computer is in one of these groups, the title is not available even if the computer is in a pilot or release group.
+              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.
 
               When using the --excluded-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.
 
@@ -478,6 +667,7 @@ module Xolo
               It will never be available to excluded computers.
 
               Self Service is not available for titles with the release_group 'all'.
+              To remove the self-service option, use --no-self-service.
             ENDDESC
           },
 
@@ -609,12 +799,50 @@ module Xolo
             desc: <<~ENDDESC
               The currently released version
             ENDDESC
+          },
+
+          # @!attribute ted_id_number
+          #   @return [Integer] The Windoo::SoftwareTitle#softwareTitleId
+          ted_id_number: {
+            label: 'Title Editor ID',
+            type: :integer,
+            cli: false,
+            changelog: false,
+            read_only: true, # maintained by the server, not editable by xadm
+            desc: <<~ENDDESC
+              The id number of the matching Software Title in the Title Editor
+            ENDDESC
+          },
+
+          # @!attribute jamf_patch_title_id
+          #   @return [Integer] The Windoo::SoftwareTitle#softwareTitleId
+          jamf_patch_title_id: {
+            label: 'Jamf Patch Title ID',
+            type: :integer,
+            cli: false,
+            changelog: false,
+            read_only: true, # maintained by the server, not editable by xadm
+            desc: <<~ENDDESC
+              The id number of the matching Patch Title in the Jamf Pro
+            ENDDESC
           }
 
         }.freeze
 
-        ATTRIBUTES.each_key do |attr|
+        ATTRIBUTES.each do |attr, deets|
           attr_accessor attr
+
+          # boolean attrs get a ? method
+          alias_method "#{attr}?", attr if deets[:type] == :boolean
+
+          next unless deets[:multi]
+
+          # ensure that multi value attrs return an empty array if nil
+          define_method attr do
+            iv = "@#{attr}"
+            instance_variable_set(iv, []) if instance_variable_get(iv).nil?
+            instance_variable_get(iv)
+          end
         end
 
         # Constructor
@@ -632,13 +860,26 @@ module Xolo
         ######################
 
         # the latest version of this title in Xolo
-        # @param cnx [Faraday::Connection] The connection to use, must be logged in already
         # @return [String]
         ####################
         def latest_version
           version_order&.first
         end
 
+        # Is this a managed title?
+        # @return [Boolean]
+        #######################
+        def managed?
+          !subscribed?
+        end
+
+        # Does this title get its pkgs from AutoPkg?
+        # @return [Boolean]
+        ############################
+        def autopkg_enabled?
+          autopkg_recipe && autopkg_dir
+        end
+
       end # class Title
 
     end # module BaseClasses

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

@@ -110,6 +110,7 @@ module Xolo
             label: 'Publish Date',
             type: :time,
             default: -> { Time.now.to_s },
+            title_type: Xolo::MANAGED,
             do_not_inherit: true,
             cli: :d,
             validate: true,
@@ -128,6 +129,7 @@ module Xolo
             label: 'Minimum OS',
             cli: :o,
             type: :string,
+            title_type: Xolo::MANAGED,
             required: false,
             validate: true,
             default: DEFAULT_MIN_OS,
@@ -145,6 +147,7 @@ module Xolo
             label: 'Maximum OS',
             cli: :O,
             type: :string,
+            title_type: Xolo::MANAGED,
             validate: true,
             changelog: true,
             # default: Xolo::NONE,
@@ -160,12 +163,14 @@ module Xolo
             label: 'Reboot',
             cli: :r,
             type: :boolean,
+            title_type: Xolo::MANAGED,
             validate: :validate_boolean,
             ted_attribute: :reboot,
             default: false,
             changelog: true,
             desc: <<~ENDDESC
               The installation of this version requires the computer to reboot. Users will be notified before installation.
+              To remove the reboot option, use --no-reboot.
             ENDDESC
           },
 
@@ -175,12 +180,14 @@ module Xolo
             label: 'Standalone',
             cli: :s,
             type: :boolean,
+            title_type: Xolo::MANAGED,
             validate: :validate_boolean,
             default: true,
             ted_attribute: :standalone,
             changelog: true,
             desc: <<~ENDDESC
               The installer for this version is a full installer, not an incremental patch that must be installed on top of an earlier version.
+              To remove the standalone option, use --no-standalone.
             ENDDESC
           },
 
@@ -190,7 +197,10 @@ module Xolo
             label: 'KillApps',
             cli: :k,
             type: :string,
+            title_type: Xolo::MANAGED,
             multi: true,
+            readline: true,
+            readline_prompt: 'KillApp',
             validate: true,
             changelog: true,
             # default: Xolo::NONE,
@@ -209,6 +219,29 @@ module Xolo
               use them as a killapp by specifying '#{USE_TITLE_FOR_KILLAPP}'
 
               If not using --walkthru you can use --killapps multiple times
+              To remove all killapps, use '#{Xolo::NONE}'.
+            ENDDESC
+          },
+
+          # @!attribute patch_unknown
+          #   @return [Boolean] Should 'unknown' versions of this title be updated to this version automatically?
+          patch_unknown: {
+            label: 'Patch Unknown Versions',
+            cli: :U,
+            type: :boolean,
+            validate: :validate_boolean,
+            default: false,
+            changelog: true,
+            desc: <<~ENDDESC
+              Should 'unknown' versions of this title be updated to this version automatically by Jamf Patch Management?
+
+              When Jamf Patch determines that a title is installed on a computer, but version reported is not among those known to Jamf Patch, it marks the version as 'unknown'. Setting this option to true will cause Jamf Patch to automatically install the pkg for this version on those Macs with 'unknown' versions.
+
+              This can cause problems if that unknown version is actually newer than this version, e.g. a beta or pre-release version, or when the app has a 'self-update' mechanism that installs newer versions outside of Jamf Patch before it is aware of them.
+
+              But sometimes it may be desirable to have all unknown versions updated to this version, e.g. when the title is a helper app that is not regularly updated, or when the title is being newly managed by Xolo/Jamf Patch and you want to get all existing installations onto this version.
+
+              To remove the patch-unknown option, use --no-patch-unknown.
             ENDDESC
           },
 
@@ -217,7 +250,6 @@ module Xolo
           #     updated for piloting
           pilot_groups: {
             label: 'Pilot Computer Groups',
-            # default: Xolo::NONE,
             cli: :p,
             validate: true,
             type: :string,
@@ -235,7 +267,7 @@ module Xolo
 
               When using the --pilot-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.
 
-              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 use '#{Xolo::NONE}'.
+              When adding a new version, the pilot groups from the previous version will be inherited if you don't specify any. To make the version have no pilot groups use '#{Xolo::NONE}'.
 
               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 <title> <version>`.  The members of the pilot groups are just the ones that will have it auto-installed.
             ENDDESC
@@ -247,13 +279,12 @@ module Xolo
           pkg_to_upload: {
             label: 'Upload Package',
             type: :string,
-            required: true,
             cli: :u,
             validate: true,
             readline: :get_files,
             do_not_inherit: true,
             hide_from_info: true,
-            invalid_msg: 'Invalid installer pkg. Must exist locally and be a .pkg file, or a .zip compressed old-style bundle package.',
+            invalid_msg: 'Invalid installer pkg. Must exist locally and be a flat .pkg file',
             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.
 
@@ -261,6 +292,8 @@ module Xolo
 
               It will be renamed to 'xolo-<title>-<version>.pkg' (or .zip).
               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.
             ENDDESC
           },
 
@@ -448,6 +481,7 @@ module Xolo
           # @!attribute jamf_pkg_id
           #   @return [String] The id of the Jamf Package object that installs this version.
           #      This is an integer in a string, as are all IDs in the Jamf Pro API.
+          #      TODO: Stop using pkgID - or any jamf ID, use names for accessing all jamf objects
           jamf_pkg_id: {
             label: 'Jamf Package ID',
             type: :string,
@@ -461,7 +495,7 @@ module Xolo
 
           # @!attribute jamf_pkg_file
           #   @return [String] The file name of the installer.pkg file used by the Jamf Package object to
-          #    installs this version. 'xolo-<title>-<version>.pkg' (or .zip)
+          #    installs this version. 'xolo-<title>-<version>.pkg'
           jamf_pkg_file: {
             label: 'Jamf Package File',
             type: :string,
@@ -541,7 +575,7 @@ module Xolo
           # @!attribute sha_512
           #   @return [String] The SHA512 checksum of the most recently uploaded package
           sha_512: {
-            label: 'Package Checksum',
+            label: 'Package Checksum (SHA512)',
             type: :string,
             do_not_inherit: true,
             cli: false,
@@ -554,9 +588,20 @@ module Xolo
 
         }.freeze
 
-        ATTRIBUTES.each_key do |attr|
+        ATTRIBUTES.each do |attr, deets|
           attr_accessor attr
-          attr_accessor "new_#{attr}"
+
+          # boolean attrs get a ? method
+          alias_method "#{attr}?", attr if deets[:type] == :boolean
+
+          next unless deets[:multi]
+
+          # ensure that multi value attrs return an empty array if nil
+          define_method attr do
+            ivar_name = "@#{attr}"
+            instance_variable_set(ivar_name, []) if instance_variable_get(ivar_name).nil?
+            instance_variable_get(ivar_name)
+          end
         end
 
         # Constructor

data/lib/xolo/core/constants.rb

@@ -58,17 +58,21 @@ module Xolo
 
       DOT_PKG = '.pkg'
 
-      DOT_ZIP = '.zip'
-
       UNKNOWN = 'unknown'
 
       # Installer packages must have one of these extensions
-      OK_PKG_EXTS = [DOT_PKG, DOT_ZIP]
+      OK_PKG_EXTS = [DOT_PKG]
 
       # The value to use when all computers are the release-targets
       # and for all manual-install policies
       TARGET_ALL = 'all'
 
+      # Title Types
+      MANAGED = :managed
+      SUBSCRIBED = :subscribed
+      TITLE_TYPES = [MANAGED, SUBSCRIBED].freeze
+      DEFAULT_TITLE_TYPE = :managed
+
       # when this module is included
       def self.included(includer)
         Xolo.verbose_include includer, self