Skip to end of metadata
Go to start of metadata

Introduction 

The Batch Installer solution is available for the installation and update of the JobScheduler Universal Agent. It allows installation of any number of Agents on multiple servers across a range of environments.

Article Scope

A general description of the installation of the JobScheduler Universal Agent can be found in the JobScheduler Universal Agent - Installation & Operation article.

In addition, a number of "How to ..." articles are available describing the use of the Batch Installer in different environments. These are linked from the JobScheduler Universal Agent - Batch Installation and Update of Agents article.

This article contains reference information for users seeking more detailed information than provided in the batch installation in different environments articles.

Feature Availability

FEATURE AVAILABILITY STARTING FROM RELEASE 1.10

The JobScheduler Universal Agent Batch Installer is available with  JITL-214 - Getting issue details... STATUS

Universal Agent Batch Installer Components

The Batch Installer is operated by a JobScheduler Master that:

  • connects to the Servers that the Agents are to be installed on and
  • executes the required Agent installations.

The Batch Installer application has two main components:

  • a JobScheduler AgentBatchInstaller job and
  • a JobScheduler universal_agent_installer job chain.

In addition, two XML files are needed for the application:

  • batch_installer_config_file.xml and 
  • yade_agent_batch_installer_settings.xml 

The AgentBatchInstaller job is responsible for creating the JobScheduler orders for the job chain. Each of these orders is named according to the pattern <host>:<port> to convey the host and port of the server where each Agent is to be installed. 

The Universal Agent Batch Installer Job Chain

The universal_agent_installer job chain has four job nodes configured in series as shown in the code block and diagram below:

Job Chain: universal_agent_installer.job_chain.xml

The configuration of the universal_agent_installer.job_chain.xml file
<job_chain  name="universal_agent_installer">
    <job_chain_node  state="CheckPreRequisite" job="CheckPreRequisite" next_state="Sync" error_state="error"/>
    <job_chain_node  state="Sync" job="Sync" next_state="TransferInstallationSetup" error_state="error"/>
    <job_chain_node  state="TransferInstallationSetup" job="TransferInstallationSetup" next_state="PerformInstall" error_state="error"/>
    <job_chain_node  state="PerformInstall" job="PerformInstall" next_state="success" error_state="error" on_error="suspend"/>
    <job_chain_node  state="success"/>
    <job_chain_node  state="error"/>
</job_chain>

 

The individual nodes in the job chain have the following functions:

  • CheckPreRequisite
    • Check for the correct Java version
    • Check whether a JobScheduler Universal Agent already has been installed.
      • If yes, then the Installer:
        • shuts down any instances that are possibly running
        • removes the installation
  • Sync: Wait until all prerequisites have been checked and all instances shut down.
  • TransferInstallationSetup: Transfer the installer files to the host
    • Before the transfer starts, the preprocessor will create the instance start script from the template jobscheduler_agent_instance_script.txt
    • The files that are to be transfered are specified with the <globals><transfer><file_spec=".*\.(sh|gz)$"> configuration element

      • This regular expression causes the following files to be transfered:
        • the JobScheduler Universal Agent installer files: jobscheduler_unix_universal_agent.<version>.tar.gz
        • the instance start script: jobscheduler_agent_<port>.sh
        • the installation script: jobscheduler_universal_agent_install.sh
  • PerformInstall: Start the installation using SSH.
    • The step before transfered installation script will be executed
    • The installation script installs and starts the JobScheduler Universal Agent
    • Finally the post-processing commands will be executed
      • The post-processing commands are specified with the <installation><postprocessing><command> element
      • Three commands will be executed
        • if you require additional commands, please add the call in the PerformInstall job
      • The default commands set up the autostart for JobScheduler Universal Agent on a Linux server (Ubuntu distribution)
        • echo ${ssh.sudo_password} | sudo -S cp ${install_path}/bin/jobscheduler_agent.sh /etc/init.d/jobscheduler
        • echo ${ssh.sudo_password} | sudo -S update-rc.d jobscheduler defaults

Job Parameters

All jobs have access to the following parameters. These parameters are used for the JobScheduler Universal Agent instance start script.

 

ParameterDescriptionXML
<job chain>_required_orders
The number of orders that have been created where job_chain is the value of the parameter installation_job_chain in the job AgentBatchInstaller 
agent_options.scheduler_ip_address
The IP address of the JobScheduler Universal Agents host. If no value is specified, the value from the paramter host in the ssh section will be used.installation/agent_options/scheduler_ip_address
agent_options.scheduler_http_port
The port of the JobScheduler Universal Agent. Default=4445installation/agent_options/scheduler_http_port
agent_options.java_home
 installation/agent_options/java_home
agent_options.java_options
 installation/agent_options/java_options
agent_options.scheduler_home

will be set to install_path + "/jobscheduler_agent"

Not available in XML
agent_options.scheduler_user
 installation/agent_options/scheduler_user
agent_options.scheduler_log_dir
 installation/agent_options/scheduler_log_dir
agent_options.scheduler_kill_script
 installation/agent_options/scheduler_kill_script
agent_options.scheduler_pid_file_dir
 installation/agent_options/scheduler_pid_file_dir
host
The SSH IP address of the JobScheduler Universal Agents hostinstallation/ssh/host
port
The SSH port of the JobScheduler Universal Agentinstallation/ssh/port
user
The SSH user of the JobScheduler Universal Agentinstallation/ssh/user
auth_method
The SSH authentication method of the JobScheduler Universal Agentinstallation/ssh/auth_method
auth_file
The SSH authentication file of the JobScheduler Universal Agentinstallation/ssh/auth_file
password
The password for the SSH userinstallation/ssh/password
sudo_password
The sudo password for the SSH userinstallation/ssh/sudo_password
install_path
The folder to which the JobScheduler Universal Agent will be installedinstallation/install_path

Job: TransferInstallationSetup

This job uses the YADE JITL job to transfer the installer files to the host.

More detailed explanations of the parameters are available with the YADE - Documentation.

It is recommended that the YADE settings file is specified with the <globals> element and that the default profile name <host>:<port> is used. The <installation><transfer> element is not then required for the installer configuration file.

ParameterDescriptionXML
settings
the file with the profiles, one for each JobScheduler Universal Agentinstallation/transfer/settings
profile
the name of the profile for the current installation. Default=<host>:<port>installation/transfer/profile
file_spec
a regular expression that defines the set of files that should be transferedinstallation/transfer/file_spec
target_host
the host to which the files should be transferedinstallation/transfer/target/host
target_port
the port according to the given protocol, e.g. 21 for the FTP protocolinstallation/transfer/target/port
target_protocol
the protocol with which the installation files will be transfered (FTP, SFTP, file, local)installation/transfer/target/protocol
target_user
the user (if required by the protocol) with which the installation files will be transferedinstallation/transfer/target/user
target_password
the password (if required by the protocol) with which the installation files will be transferedinstallation/transfer/target/password
target_dir
the location that the files will be copied toinstallation/transfer/target/dir
target_ssh_auth_method
the authentication method should the SSH protocol be usedinstallation/transfer/target/auth_method
target_ssh_auth_file
the authentication file should the the SSH protocol be used and the target_ssh_auth_method parameter be used with the value publickeyinstallation/transfer/target/auth_file
source_host
the host from which the installation files should be transferedinstallation/transfer/source/host
source_port
the port according to the given protocol (e.g. 21 when protocol is ftp)installation/transfer/source/port
source
the protocol with which the source will be transferred (ftp, sftp, file, local)installation/transfer/source/protocol
source_user
the user (if the protocol needs one) with which the source will be transferredinstallation/transfer/source/user
source_password
the password (if the protocol needs one) with which the source will be transferredinstallation/transfer/source/password
source_dir
the location from where the files will be copiedinstallation/transfer/source/dir
source_ssh_auth_method
the authentication method if the protocol is ssh.installation/transfer/source/auth_method
source_ssh_auth_file
the authentication file if the protocol is ssh and auth_method is publickeyinstallation/transfer/source/auth_file

Job: PerformInstall

More detailed explanations of the parameters are available with the JITL SSH job documentation

ParameterDescriptionXML
command_n
n = 0...  The commands for the post-processing, e.g. enabling the autostart of the Universal Agentinstallation/postprocessing/command
command_counter
The number of commands specified 

Starting the update/installation

The update/installation procedure is started by running the AgentBatchInstaller job, which is described in the next section.

The AgentBatchInstaller Job

The job AgentBatchInstaller reads the installer configuration file and creates orders for each element <installation>.

The element <installation> defines the source and the target of the installer files, the port for the JobScheduler Universal Agent and the SSH connection parameters. Please note:

  • You can define defaults for all elements in the <globals> element.
  • You can use variables for values e.g. ${ssh.host}.
  • It is recommended that you specify the name of the YADE settings file in the <globals> element and use the default profile name as shown in the example Configuration File below. This will mean that it is not necessary to define <installation><transfer> elements.

Parameters for the AgentBatchInstaller Job

ParameterDescriptionExample
installation_definition_file
The XML file that contains all parameters for the batch installationc:\batch\batchinstall.xml
filter_install_host
A host name if only one order should be created that matches the given hostmyAgent
filter_install_port
A port if only one order should be created that matches the given host

4445

installation_job_chain
The name of the job chain for which the orders should be created/batch_install_universal_agent/universal_agent_installer
update

If true then an order for all <instances> will be created.

If false then an order for <instances> that do not have the last_run attribute will be created

true

Customizing the Installation Process

The installation process can be customized as follows.

  • The scripts in the CheckPreRequisite and PerformInstall SSH jobs can be modified.
    • Use this if you want to check other prerequisites or execute additional commands either before or after the installation.
  • The jobscheduler_universal_agent_install.sh installation script can be modified.
  • The template for the jobscheduler_agent_instance_script.txt start script for the Agent instances can be modified.

Checking Prerequisites

The CheckPreRequisite job will check the Java version, shut down any JobScheduler Universal Agent that may be running and remove the lib folder from an existing installation.

echo .JobScheduler Universal Agent
echo .checking prerequisites ${install_path}
echo .checking Java Runtime Version >= 1.8? ......
JAVA_VER=$(java -version 2>&1 | sed 's/java version "\(.*\)\.\(.*\)\..*"/\1\2/; 1q')
if [ "$JAVA_VER" > "18" ]
then
  echo ..java version: $JAVA_VER ok
else
  echo ..wrong Java version found
  echo ..expectet version is >= 1.8
  echo ..installed version is $JAVA_VER
  exit 8
fi
echo .checking whether JobScheduler Universal Agent is already installed?
if [ -f ${install_path}/jobscheduler_agent/bin/jobscheduler_agent.sh ]
then
  echo ..JobScheduler Universal Agent already installed
  echo ..shutting down JobScheduler Universal Agent 
  ${install_path}/jobscheduler_agent/bin/jobscheduler_agent.sh stop
  echo ..removing installation from  ${install_path}
  rm -Rf ${install_path}/lib
else
  echo .. this is the first installation of JobScheduler Universal Agent 
fi
exit $?

Performing the Installation

The PerformInstall job calls the installation script and executes the commands specified with the <postprocessing> element.

echo Executing PerformInstall ${target_dir}
echo ${sudo_passwort} | sudo -S chmod a+x ${target_dir}/jobscheduler_universal_agent_install.sh 
echo ${sudo_passwort} | sudo -S ${target_dir}/jobscheduler_universal_agent_install.sh -d${install_path} -p${agent_options.scheduler_http_port}
${command_0}
${command_1}
${command_2}

The Installation Script

The installation script will unzip the Agent installation file and start the JobScheduler Universal Agent.

The Agent Installation Script
#!/bin/sh 
# Copyright (c) 2015 SOS GmbH, Berlin, Germany.
# All rights reserved.
export TERM=dumb
  clear
  echo "+---------------------------------------------------------+"
  echo "*     JobScheduler Univeral Agent                         *"
  echo "*     SOS Software- und Organisations Service GmbH        *" 
  echo "*     Giesebrechtstr. 15                                  *"
  echo "*     10629 Berlin                                        *"
  echo "*     ----------------------------------------------      *"
  echo "*     info@sos-berlin.com                                 *"
  echo "*     http://www.sos-berlin.com                           *"
  echo "+---------------------------------------------------------+"
  echo ""
  echo ""
  echo "+---------------------------------------------------------+"
  echo "*  This will install JobScheduler Universal Agent now ... *"
  echo "+---------------------------------------------------------+"
 
# -----------------------------------------------
cd `dirname $0`
  
SETUP_WORKING_DIR=`pwd` 
SETUP_INSTALL_PATH=""
SHOW_EXTRACTED_FILESNAMES=0
SETUP_LOG_FILE="$SETUP_WORKING_DIR/jobscheduler_universal_install.log"
SETUP_ERR=0
 


# ----------------------------------------------------------------- 
log_write() {
  case "$1" in
      0  ) msg_hint="[info]   ";;
      1  ) msg_hint="[warning]";;
      2  ) msg_hint="[error]  ";;
      3  ) msg_hint="[fatal]  ";;
      *  ) msg_hint="[info]   ";;
  esac
  timestamp=`date "+%Y-%m-%d %T"`
  msg="$timestamp   $msg_hint   $2"
  echo "$msg"
  echo "$msg">>"$SETUP_LOG_FILE"
}

show_usage() {
  echo "`basename $1` will install the 'JobScheduler Universal Agent' at [install_dir]." 
  echo "install_dir=Path with the JobScheduler Universal Agent"
  echo
  echo "Usage: `basename $1` [OPTION]"
  echo
  echo "Samples:"
  echo "  `basename $1` -co  -d/home/jobscheduler  -p4445 "      
  echo 
  echo "Options:"
  echo "  -h, --help                          | Shows this usage"
  echo "  -s, --show                          | show all extracted filenames"
  echo "  -w  --install_dir                   | Path of the JobScheduler Universal Agent installation"
  echo "  -p  --port                          | Port of JobScheduler Universal Agent. Default=4445"
 
}
 
# ----------------------------------------------------------------------------usage
if [ $# -eq 0 ]
then
  show_usage $0
  exit 65
fi 



# --------------------------------------------
     

for arg in "$@"
do
  long_opt=0
  echo "`expr match $arg '\(..\)'`" 
  case "`expr match $arg '\(..\)'`" in
    "-h"        )  show_usage $0; exit 64;;
    "-d"        )  SETUP_INSTALL_PATH="`expr match $arg '-d\(.*\)'`";;
    "-p"        )  UNIVERSAL_AGENT_PORT="`expr match $arg '-p\(.*\)'`";;
    "-s"        )  SHOW_EXTRACTED_FILESNAMES="`expr match $arg '-d\(.*\)'`";;
    "--"        )  long_opt=1;;
  esac 
  
  if [ "$long_opt" -eq 1 ]
  then
  case `expr match "$arg" '\(--[^=]*\)'` in
    "--show_extracted_filenames"    )  SHOW_EXTRACTED_FILESNAMES=`expr match "$arg" '--.*=\(.*\)'`;;
    "--help"    )  show_usage $0; exit 64;;
    "--install_dir"    )  SETUP_INSTALL_PATH=`expr match "$arg" '--.*=\(.*\)'`;;
    "--port"    )  UNIVERSAL_AGENT_PORT=`expr match "$arg" '--.*=\(.*\)'`;;
  esac
  fi

done

 
# ---------------

  
check_dir(){
     SETUP_INSTALL_PATH="$1"
     echo SETUP_INSTALL_PATH="$SETUP_INSTALL_PATH"

     if [ -d "$SETUP_INSTALL_PATH" ]
     then
       if [ -r "$SETUP_INSTALL_PATH" ]
       then
         cd "$SETUP_INSTALL_PATH"
         SETUP_INSTALL_PATH=`pwd`
         chmod 700 "$SETUP_INSTALL_PATH" 2>/dev/null
         SETUP_ERR=$?
       else
         log_write 2 "$SETUP_INSTALL_PATH is not readable."
         SETUP_ERR=1
       fi
     else
       echo create $SETUP_INSTALL_PATH

       mkdir -m700 -p "$SETUP_INSTALL_PATH" 2>/dev/null
       SETUP_ERR=$?
       if [ $SETUP_ERR -eq 0 ]
       then
      
         cd  "$SETUP_INSTALL_PATH"
         SETUP_INSTALL_PATH=`pwd`
       else
         log_write 2 "$SETUP_INSTALL_PATH can not create."
         SETUP_ERR=1 
       fi
     fi
     
     
     cd  "$SETUP_WORKING_DIR"
     if [ $SETUP_ERR -ne 0 ]
     then
        log_write 2 "You haven't the necessary rights on the installation directory $SETUP_INSTALL_PATH."
     exit $SETUP_ERR
fi
}

tarx (){
  if [ -f "$1.gz" ]
  then
     gzip -fd $1.gz
  fi
  
  if [ ! -d "$2" ]
  then
      mkdir $2
  fi
 
  cd  $2
  tar $tarpar $SETUP_WORKING_DIR/$1
  cd  $SETUP_WORKING_DIR
} 

tarpar="-xf "

if [ "$SHOW_EXTRACTED_FILESNAMES" = "1" ]
then
   tarpar="-xvf "
fi


SETUP_INSTALL_PATH="$SETUP_INSTALL_PATH"

echo SETUP_INSTALL_PATH=$SETUP_INSTALL_PATH
check_dir $SETUP_INSTALL_PATH
  

# Installing
log_write 0 "Installing --> $SETUP_INSTALL_PATH"
tarx  jobscheduler_unix_universal_agent.tar  $SETUP_INSTALL_PATH 

if [ -z "$UNIVERSAL_AGENT_PORT" ]
then
$UNIVERSAL_AGENT_PORT=4445
fi

mv `dirname $0`/jobscheduler_agent_$UNIVERSAL_AGENT_PORT.sh $SETUP_INSTALL_PATH/jobscheduler_agent/bin 
chmod a+x  $SETUP_INSTALL_PATH/jobscheduler_agent/bin/jobscheduler_agent_$UNIVERSAL_AGENT_PORT.sh   
log_write 0 "Start JobScheduler Universal Agent"
log_write 0 $SETUP_INSTALL_PATH/jobscheduler_agent/bin/jobscheduler_agent_$UNIVERSAL_AGENT_PORT.sh start
$SETUP_INSTALL_PATH/jobscheduler_agent/bin/jobscheduler_agent_$UNIVERSAL_AGENT_PORT.sh start 1 > /dev/null

exit $?

The Installer Configuration File

The installer configuration file contains an <installation> element for each JobScheduler Universal Agent instance.

The following code block shows a minimal example for the installer configuration file:

A Simple Example Agent Installation File
 <?xml version="1.0" encoding="utf-8"?>
<installations lastRun="2015-11-06 15:11">
  <globals>
    <transfer>
      <settings><![CDATA[C:\Temp\batch_install\yade_agent_batch_installer_settings.ini]]></settings>
    </transfer>
  </globals>
  <installation lastRun="2015-11-06 15:11">
    <install_path><![CDATA[/home/test/temp/xxx]]></install_path>
    <agent_options>
      <scheduler_http_port>4445</scheduler_http_port>
      <scheduler_ip_address><![CDATA[192.11.0.116]]></scheduler_ip_address>
    </agent_options>
    <ssh>
      <user><![CDATA[test]]></user>
      <password><![CDATA[12345]]></password>
      <sudo_password><![CDATA[12345]]></sudo_password>
      <auth_method><![CDATA[password]]></auth_method>
      <port><![CDATA[22]]></port>
    </ssh>
    <postprocessing>
      <command><![CDATA[echo ${ssh.sudo_password} | sudo -S cp ${install_path}/bin/jobscheduler_agent.sh /etc/init.d/jobscheduler]]></command>
      <command><![CDATA[echo ${ssh.sudo_password} | sudo -S update-rc.d jobscheduler defaults]]></command>
    </postprocessing>
  </installation>
</installations>

 

The <globals> element is used to specify values that are used for all installation items. The items that are specific for an individual installation will overwrite the global values. An installation item is required for each Agent. You can use substitution in the values of the elements.

<command>echo ${ssh.sudo_password} | sudo cp ${install_path}/bin/jobscheduler_agent.sh /etc/init.d/jobscheduler</command>

Using the XML Editor to Configure Files

Configuring complex XML files with a text editor is often a tedious and error-prone procedure. To get around this, we recommend that you use our XML Editor to manage the configuration files required for the Batch Installer. The XML Editor automatically validates configuration files and therefore reduces the possibility of configuration errors. 

Find more details from our XML Editor article.

  • After downloading the XML Editor, extract the zip file, then start the "sos.xml.editor.exe" file. (The XML Editor runs on Windows systems and does not need to be installed.)
  • Open your installer configuration file in the Editor and assign the XSD scheduler_universal_agent_installations.xsd schema.

Managing the YADE file transfer profiles

Each installation makes use of a profile in the YADE settings file. The default profile name is <host>:<port> where:

  • <host> is substituted with the value from the element <installation><agent_option><scheduler_ip_address> and
  • <port> is substituted with the value from the element <installation><agent_option><scheduler_http_port>
  1. Specify the name of the YADE settings file with the <globals><settings> element.
  2. Open the YADE settings file or create a new one.
  3. Assign the XSD Schema http://www.sos-berlin.com/schema/yade/YADE_configuration_v1.0.xsd
  4. Add a <ProtocolFragments> element and nodes for each host that you want to install the JobScheduler Universal Agent for.
  5. Add a <Profile> element and nodes for each host you want install the JobScheduler Universal Agent for.
  6. The default profile_id is <host>:<port>. If you do not use the default then you have to specify the profile name in the installer configuration file.

Change Management References - Batch Installation

T Key Linked Issues Fix Version/s Status P Summary Updated
Loading...
Refresh

Write a comment…