lib/jamf/api/connection.rb
# Connect this Connection object to an Jamf Pro API
#
# The first parameter may be a URL (must be https) from which
# the host & port will be used, and if present, the user and password
# E.g.
#   connect 'https://myuser:pass@host.domain.edu:8443'
#
# which is the same as:
#   connect host: 'host.domain.edu', port: 8443, user: 'myuser', pw: 'pass'
#
# When using a URL, other parameters below may be specified, however
# host: and port: parameters will be ignored, since they came from the URL,
# as will user: and :pw, if they are present in the URL. If the URL doesn't
# contain user and pw, they can be provided via the parameters, or left
# to default values.
#
# ### Passwords
# The pw: parameter also accepts the symbols :prompt, and :stdin[X]
#
# If :prompt, the user is promted on the commandline to enter the password
# for the :user.
#
# If :stdin the password is read from the first line of stdin
#
# If :stdinX (where X is an integer) the password is read from the Xth
# line of stdin.see {Jamf.stdin}
#
# If omitted, and running from an interactive terminal, the user is
# prompted as with :prompt
#
# ### Tokens
# Instead of a user and password, you may specify a valid 'token:', either:
#
# A Jamf::Connection::Token object, which can be extracted from an active
# Jamf::Connection via its #token method
#
# or
#
# A token string e.g. "eyJhdXR...6EKoo" from any source can also be used.
#
# Any values available via Jamf.config will be used if they are not provided
# in the parameters.
#
# @param host: [String] The API server hostname. The param 'server:' is a
#   synonym
#
# @param port: [Integer] The API server port. If omitted, the value from
#   Jamf.config will be used. If no config value, defaults to 443 if the
#   host ends with 'jamfcloud.com' or 8443 otherwise
#
# @param user: [String] The username for the API connection
#
# @param pw: [String, Symbol] The password for the user, :prompt, or :stdin[X]
#
# @param token: [Jamf::Connection::Token, String] An existing, valid token.
#   When used, there's no need to provide user: or pw:.
#   NOTE if using pw_fallback:true (the default) while providing a token
#   you will also need to provide the password for the token user in the pw:
#   parameter, or be prompted for it. If you don't have the pw for the
#   token user, be sure to set pw_fallback to false.
#
# @param token_refresh: [Integer] Refresh the token this many seconds before
#   it expires. Must be >= DFT_TOKEN_REFRESH
#
# @pararm pw_fallback: [Boolean] Default is true. Use the password provided
#   to refresh the token if regular refresh doesn't work (e.g. token is expired).
#   NOTE: This causes the password to be kept in memory. If you don't want
#   this, explicitly set pw_fallback to false, however long-running processes
#   may lose connection if token refresh fails for any reason.
#
# @param open_timeout: [Integer] The number of seconds for initial contact
#   with the host.
#
# @param timeout: [Integer] The number of seconds for a full response from
#   the host.
#
# @param ssl_version: [Symbol] The SSL version, e.g. :TLSv1_2
#
# @param verify_cert: [Boolean] Should the SSL certificate be verified?
#   Default is true, should only be set to false if using a on-prem
#   server with a self-signed certificate, which is rare
#
Connect this Connection object to an Jamf Pro API
The first parameter may be a URL (must be https) from which
the host & port will be used, and if present, the user and password
E.g.



When using a URL, other parameters below may be specified, however
host: and port: parameters will be ignored, since they came from the URL,
as will user: and :pw, if they are present in the URL. If the URL doesn't
contain user and pw, they can be provided via the parameters, or left
to default values.

Passwords
The pw: parameter also accepts the symbols :prompt, and :stdin[X]

If :prompt, the user is promted on the commandline to enter the password
for the :user.

If :stdin the password is read from the first line of stdin

If :stdinX (where X is an integer) the password is read from the Xth
line of stdin.see {Jamf.stdin}

If omitted, and running from an interactive terminal, the user is
prompted as with :prompt

Tokens
Instead of a user and password, you may specify a valid 'token:', either.



or



Any values available via Jamf.config will be used if they are not provided
in the parameters.
Connect this Connection object to an Jamf Pro API The first parameter may be a URL ( must be https ) from which the host & port will be used and if present the user and password E . g . When using a URL other parameters below may be specified however host : and port : parameters will be ignored since they came from the URL as will user : and : pw if they are present in the URL . If the URL doesn ' t contain user and pw they can be provided via the parameters or left to default values . Passwords The pw : parameter also accepts the symbols : prompt and : stdin [ X ] If : prompt the user is promted on the commandline to enter the password for the : user . If : stdin the password is read from the first line of stdin If : stdinX ( where X is an integer ) the password is read from the Xth line of stdin . see { Jamf . stdin } If omitted and running from an interactive terminal the user is prompted as with : prompt Tokens Instead of a user and password you may specify a valid ' token : ' either . or Any values available via Jamf . config will be used if they are not provided in the parameters .
def connect(url = nil, **params)
      disconnect
      parse_token params
      parse_url url, params
      apply_connection_defaults params
      verify_basic_params params
      parse_connect_params params
      unless @token
        if params[:token].is_a? String
          @token = token_from :token_string, params[:token]
          @user = @toke.user
          @pw = acquire_password(params[:pw]) if @pw_fallback
        else
          pw = acquire_password(params[:pw])
          @token = token_from :pw, pw
          @pw = pw if @pw_fallback
        end
      end
      @base_url = @token.base_url
      @login_time = @token.login_time
      @rest_cnx = create_connection
      validate_jamf_version
      @connected = true
      start_keep_alive if @keep_alive
      to_s
    end
def connect ( url = nil , ** params ) disconnect parse_token params parse_url url , params apply_connection_defaults params verify_basic_params params parse_connect_params params unless @token if params [ :token ] . is_a? String @token = token_from :token_string , params [ :token ] @user = @toke . user @pw = acquire_password ( params [ :pw ] ) if @pw_fallback else pw = acquire_password ( params [ :pw ] ) @token = token_from :pw , pw @pw = pw if @pw_fallback end end @base_url = @token . base_url @login_time = @token . login_time @rest_cnx = create_connection validate_jamf_version @connected = true start_keep_alive if @keep_alive to_s end
Connect this Connection object to an Jamf Pro API
The first parameter may be a URL (must be https) from which
the host & port will be used, and if present, the user and password
E.g.
Connect this Connection object to an Jamf Pro API The first parameter may be a URL ( must be https ) from which the host & port will be used and if present the user and password E . g .
# This sets all the instance vars to nil, and flushes/creates the caches # If there's a Token object in :token, this sets @token, # and adds host, port, user from that token # Get host, port, user and pw from a URL, add to params if needed # apply defaults from config, client, and then this class. # Once we're here, all params have been parsed & defaulted into the # params hash, so # make sure we have the minimum needed params for a connection # turn the params into instance vars # if no @token already, get one from from # either a token string or a pw # get the user from the token # if @pw_fallback, the pw must be acquired, since it isn't in # the token # Now get some values from our token # and make our actual connection # make sure versions are good # start keepalive if needed # return our string output
url
params
host:
The API server hostname. The param 'server:' is a synonym
The API server hostname . The param ' server : ' is a synonym
port:
The API server port. If omitted, the value from Jamf.config will be used. If no config value, defaults to 443 if the host ends with 'jamfcloud.com' or 8443 otherwise
The API server port . If omitted the value from Jamf . config will be used . If no config value defaults to 443 if the host ends with ' jamfcloud . com ' or 8443 otherwise
443 if the host ends with 'jamfcloud.com' or 8443 otherwise
user:
The username for the API connection
The username for the API connection
pw:
The password for the user, :prompt, or :stdin[X]
The password for the user : prompt or : stdin [ X ]
token:
An existing, valid token. When used, there's no need to provide user: or pw:. NOTE if using pw_fallback:true (the default) while providing a token you will also need to provide the password for the token user in the pw: parameter, or be prompted for it. If you don't have the pw for the token user, be sure to set pw_fallback to false.
An existing valid token . When used there ' s no need to provide user : or pw : . NOTE if using pw_fallback : true ( the default ) while providing a token you will also need to provide the password for the token user in the pw : parameter or be prompted for it . If you don ' t have the pw for the token user be sure to set pw_fallback to false .
token_refresh:
Refresh the token this many seconds before it expires. Must be >= DFT_TOKEN_REFRESH
Refresh the token this many seconds before it expires . Must be > = DFT_TOKEN_REFRESH
open_timeout:
The number of seconds for initial contact with the host.
The number of seconds for initial contact with the host .
timeout:
The number of seconds for a full response from the host.
The number of seconds for a full response from the host .
ssl_version:
The SSL version, e.g.
The SSL version e . g .
verify_cert:
Should the SSL certificate be verified. Default is true, should only be set to false if using a on-prem server with a self-signed certificate, which is rare
Should the SSL certificate be verified . Default is true should only be set to false if using a on - prem server with a self - signed certificate which is rare
pararm
[Boolean] Default is true. Use the password provided to refresh the token if regular refresh doesn't work . NOTE: This causes the password to be kept in memory. If you don't want this, explicitly set pw_fallback to false, however long-running processes may lose connection if token refresh fails for any reason.
[ Boolean ] Default is true . Use the password provided to refresh the token if regular refresh doesn ' t work . NOTE : This causes the password to be kept in memory . If you don ' t want this explicitly set pw_fallback to false however long - running processes may lose connection if token refresh fails for any reason .