Automic Agent Deployment
and Upgrade Toolkit
How-To Documentation
Table of Contents
AUTOMIC AGENT DEPLOYMENT AND UPGRADE TOOLKIT ...................................................... 4
Introduction ...................................................................................................................................... 4
Overview ........................................................................................................................................... 4
Benefits ............................................................................................................................................. 4
Compatibility ..................................................................................................................................... 5
Key Considerations ............................................................................................................................ 6
Disclaimer.......................................................................................................................................... 8
PREREQUISITES ..................................................................................................................... 9
General.............................................................................................................................................. 9
Windows Specific Prerequisites ........................................................................................................ 10
UNIX Specific Prerequisites .............................................................................................................. 11
OBJECT SETUP ..................................................................................................................... 13
Folder Structure ............................................................................................................................... 13
Agent Groups................................................................................................................................... 13
HOSTG.AGENT_DEPLOY.JAVA ................................................................................................................. 13
HOSTG.AGENT_DEPLOY.FTP.................................................................................................................... 14
HOSTG.AGENT_DEPLOY.WIN .................................................................................................................. 14
Logins .............................................................................................................................................. 14
LOGIN.AGENT_DEPLOY. .......................................................................................................................... 14
Workflows ....................................................................................................................................... 15
JOBP.AGENT_DEPLOY.UNIX.INSTALL_AGENT_AND_SMGR .................................................................... 15
PRPT.AGENT_DEPLOY.UNIX.SETUP ................................................................................................. 15
PRPT.AGENT_DEPLOY.UNIX.AGENT_SMGR__INI_CHANGES.......................................................... 16
JOBP.AGENT_DEPLOY.WIN.INSTALL_AGENT_AND_SMGR ..................................................................... 17
PRPT.AGENT_DEPLOY.WIN.SETUP .................................................................................................. 17
PRPT.AGENT_DEPLOY.WIN.AGENT_SMGR__INI_CHANGES ........................................................... 18
Scripts ............................................................................................................................................. 19
SCRI.AGENT_DEPLOY.MAIN.INSTALL_MULTIPLE_AGENTS ..................................................................... 19
PRPT.AGENT_DEPLOY.MAIN_SCRIPT_SETUP.................................................................................. 19
SCRI.AGENT_DEPLOY.MAIN.INSTALL_ONE_AGENT ................................................................................ 20
PRPT.AGENT_DEPLOY.MAIN_SCRIPT_SETUP.................................................................................. 20
EXECUTION ......................................................................................................................... 22
2
Update ‘server_list.csv’ .................................................................................................................... 22
General .................................................................................................................................................... 22
Encrypting A Password ............................................................................................................................ 22
Creating an Existing Agent Upgrade File ................................................................................................. 23
Update ‘versions.csv’ (if needed) ...................................................................................................... 24
Update ‘config.ini’ (if needed) .......................................................................................................... 24
Verify Information in All Prompt Sets ............................................................................................... 25
Executing the Solution ..................................................................................................................... 25
General .................................................................................................................................................... 25
Preliminary Check.................................................................................................................................... 25
Checking status of agent installation/upgrade .................................................................................. 26
3
AUTOMIC AGENT DEPLOYMENT AND UPGRADE
TOOLKIT
Introduction
Deploying Automic agents has always been a manual process for customers. Whether you are a new
customer who is just starting to use Automic or an existing customer upgrading to the latest release,
agent deployment will be a requirement. For customers with less than 10-20 agents, the effort to deploy
agents may be manageable. However, for those with more, the work can take anywhere from a few
days up to a few weeks. Customers who have hundreds or thousands of agents are using valuable time
and company resources to complete this process. They should instead be using that time and those
resources to focus on other business requirements.
Depending on the level of expertise with Automic, it can take a few minutes up to 20 minutes to
manually deploy just one agent. In addition, if only one company resource is assigned this task, then
each agent is installed/upgraded one at a time. Customers also run the risk of incorrectly editing agent
config files which can only slow down the deployment process, or possibly cause problems later on if not
caught early.
To improve the agent deployment process, Automic has developed the Agent Deployment and Upgrade
Toolkit. The solution can free up time and resources for customers, as well as cut costs. This document
describes the toolkit and its benefits, along with details on setup and execution.
Overview
The Agent Deployment and Upgrade Toolkit was designed to automate the installation and upgrade of
agents. The current method for agent deployment is a manual process so this solution reduces the time,
resources, and costs involved.
The toolkit works directly with the Automation Engine. This means that the customer can execute
objects within the User Interface to initiate the installation/upgrade, and then the Automation Engine
will communicate with the server to deploy the agent.
Benefits

Significantly minimizes the time it takes to deploy hundreds to thousands of agents. Total time
can be reduced from days/weeks to minutes/hours

Frees up company resources which allows the customer to focus on other tasks

Cuts costs due to reduction in time and resources needed
4

Integrates directly with the Automation Engine, allowing installations and upgrades to be
managed and monitored within the User Interface

Ensures that new agent installations use Automic’s best practices to guarantee that future
upgrades on these agents run smoothly

Upgrades existing agents in place, keeping customer’s current configuration intact

Backs up existing agent files prior to performing an upgrade

Ensures that all agents are linked with an Automic Service Manager which follows Automic’s
best practices
Compatibility
The Agent Deployment and Upgrade Toolkit must be installed with an Automation Engine that is
running V10 or higher. The solution has been tested with upgrading agents that are currently on V8 and
higher. Currently, it can only be used to install and upgrade Operating System agents. The supported
Operating Systems and corresponding architectures are listed below.




Windows
o 32-bit
o 64-bit
AIX
o Powerpc
o Powerpc64
Linux
o 32-bit
o 64-bit
Solaris
o 32-bit
o 64-bit
o Sparc
o Sparc64
5
Key Considerations
The following scenarios should be considered before using this solution:

Setup Options are applied to all agents – For multiple agent installations/upgrades, the
configurations applied during object setup will be applied to all agents. For example, the
UNIX/Windows user chosen, the agent port to use, and whether or not to keep the existing .ini
file during upgrade. These options, along with others, will be applied to all agents affected
during an execution of the solution. This is why it is important to check all Promptsets before an
execution, and also a good idea to execute the solution on groups of agents that will all require
the same settings.

INI file changes – Currently, only the options provided in the
‘PRPT.AGENT_DEPLOY.(WIN|UNIX).AGENT_SMGR__INI_CHANGES’ Promptset can be changed in
the Agent and Service Manager’s config (.ini) file.

Multiple INI/SMD/SMC Files – Some customers have set up their agents and/or service
managers where multiple config files use the same binary files. This setup is not supported by
the solution. The solution will only look for the standard files which are uc4.smd, uc4.smc, and
<agent binary name>.ini.

Finding root directory from agent installation path – In the case of an agent upgrade, the
solution pulls the agent information from the Automic database, and tries to find the root
directory from the agent’s install bin path (i.e. /opt/automic). It does this by searching for a
directory in the install path called ‘agents’ or ‘agent’ (case insensitive), and then saving the root
path as the directory one level up. If it cannot find this, then the workflow will block because the
solution has no way of determining the root installation path.

Multiple Agents on One Server – This solution only supports the installation and/or upgrade of
one agent on a server because only one install directory can be specified during setup.

Custom Agent Names – Automic recommends using the hostname of a server when naming an
agent. But in some cases customers may want to set a custom name for the agent. This
functionality can be done with the solution for new installations and upgrades. However, the
customer MUST remember to include the custom agent name when running the solution. If not,
in the case of new installations, the solution will install a new agent using the hostname. If an
upgrade was intended and the custom agent name is missing, the solution will think it needs to
install/upgrade an agent using the hostname, which could potentially install an unwanted agent
or overwrite an existing one.

Version Comparison – If there is any difference in the agent’s version on the AE system versus
the version in the downloaded image, then the agent will be upgraded. This means that even if
the agent on the AE system is on a later version than what is in the downloaded image, the
agent will still be upgraded.

New Agents and Existing Service Manager – The preferred situation when installing a new
agent is that the Service Manager will be installed new as well. If there is a Service Manager
already running and you are installing a new agent on that server, the solution will not be able
to continue because it does not have a way of detecting any details for that Service Manager.
The solution can only scan for a Service Manager via Automic using an existing agent.
6

Agents must be running for an upgrade – If an agent is to be upgraded, it should be started and
connected to the Automation Engine. The solution searches client 0 for an agent object for the
server in question. If an agent object is found and it is not running, the workflow will block.

Agents are upgraded in place – If an existing agent is located in a directory other than what was
specified during setup, then its files will be backed up to a directory with naming convention
(Agent_Backup_<Run ID>_<Date:YYMMDD>_<Time:HHMMSS>) and upgraded in the same
directory. It will not be moved to the setup directory. Keep in mind that every time the workflow
reaches the job that copies the new agent files, it will create a backup of the old files.

Rollback Unavailable– Rolling back to the previous version is not available with the solution.
This will have to be done manually which would involve removing the current agent files,
restoring the backed up files, updating file ownership if needed (for UNIX agents only), and
starting the agent (via the Service Manager, if applicable).

UNIX Agent Binary Root Ownership – Per Automic best practices, the UNIX agent binary should
be owned by root to allow jobs to be executed by any user on that server. However, some
customers cannot have the file owned by root, in which case the solution gives you the option.
Keep in mind that if the customer chooses to opt out of root ownership, the ‘login_check’ field
in the .ini file will automatically be set to ‘no’. In addition, the customer MUST set up
ANONYMOUS_FT and ANONYMOUS_JOB in the UC_HOSTCHAR_DEFAULT (or equivalent) to ‘Y’
since this is the requirement per Automic documentation.

Sudo Privileges – Temporary sudo privileges are required for some of the UNIX commands used
by the solution (see the UNIX Specific Prerequisites section for details). Sudo with NOPASSWD
set for those commands is preferred. The solution will still work if a password is required,
however, the customer must be aware that the password will be in clear text in the Job Report
of specific Automic jobs. This happens because Automic FTP jobs echo all commands to the Job
Report, which includes the password that is passed into sudo.

Service Manager Required – Per Automic best practices, a Service Manager should be installed
on any server where an Automic agent(s) runs. Along with installing/upgrading an agent, the
solution will check to see if a Service Manager is installed and linked to the AE system. NOTE:
Service Manager must be running for the solution to detect it. If not, a Service Manager will be
installed. If the solution finds one or more Service Managers already installed, but cannot
determine one that is linked to the AE system, then the solution cannot continue with the agent
installation/upgrade on that server.

Service Manager Is Not Upgraded – The Service Manager files do not typically change from one
version of Automic to the next. For this reason, if a Service Manager is found on the server
linked to the agent, it will not be upgraded. Only the agent is upgraded in this solution.

Service Manager Port – Agent servers should use the same service manager port as set up in
client 0 (Located in UC_SYSTEM_SETTINGS -> SMGR_PORT_RANGE under the DIV_VARIABLES
folder). The port number is 8871 by default, but it can be different if the Service Manager on the
AE server uses a different port.
o
Agent servers with Service Manager Already Running – If the port number on the AE
and agent server do not match, then this solution will be unable to find the Service
Manager on the agent server, and the workflow will block.
7
o
Agent servers with no Service Managers Running – In this case, the solution will install
a new service manager and will use the ‘SMGR_PORT_RANGE’ port specified in client 0.

More than one service manager running on Agent server – In some circumstances, customers
may have more than one service manager running on a particular agent server. If the solution
cannot find the service manager running on the AE’s SMGR port, then the workflow will block.
The reason for this is because the solution is unable to determine which service manager
belongs to the AE system.

UNIX Service Manager Startup – Customer will have to add a startup script on the UNIX server
to have the Automic Service Manager startup under the user it was installed. This will ensure
that the agent is running when the server boots up. If customer does not already have a script to
do this, Automic can provide one.
Disclaimer
The Agent Deployment and Upgrade Toolkit is offered as no-charge community solution. The solution is
distributed “AS IS” and without any express or implied warranty. Automic makes no representations
that the solution (i) will meet Customer’s requirements, (ii) will operate when used with other hardware,
software, systems or data not provided or expressly approved by Automic, (iii) will operate
uninterrupted or error-free, (iv) will offer Customer any network security protection or that (v) errors of
an immaterial nature will be corrected. The solution is completely end-user customizable and is
therefore provided without support or maintenance. Support can be requested from Automic
Consulting, as additional effort. On demand and after talking to Automic, small changes may be possible
as well. All rights for the solution and any changes/extensions remain the sole property of Automic.
8
PREREQUISITES
General
1. Download full AE image from Automic download site
2. Java 1.7 (JRE or JDK) installed on server where the solution’s Java files will be copied and executed. A
recommended server would be an Automation Engine server because a local OS agent should
already be installed here, but user can choose another server provided an OS agent is available.
3. Certain ports should be opened on the Automation Engine server(s) and Remote agent servers. The
default ports are listed below, but these ports may vary depending on what was specified during the
installation of the AE.
 2217 - 2220 – CP Ports
 2270 - 2279 – WP Ports
 8871 – Service Manager
 2300 – Agent Port
4. Automation Engine installed with a license that supports the type and number of agents to be
deployed
5. Agents to be upgraded must be up and running.
6. Load objects for agent deployment solution into AE client of your choice, using the DB Load utility
7. Import HSTA.AGENT_DEPLOY into folder of your choice in client 0. Export file should be included
with solution package. The purpose of this object is so that you can see when agents are
started/stopped in the client used in the previous step. If you want to assign the installed/upgraded
agents to another client, you should create another HSTA object.
Once imported, open the object and on the Authorizations tab, select all check boxes for the client
where the agent deployment objects were loaded. Afterwards, open System Overview, click Agent
Assignment in the left panel, and drag the HSTA object in the Inactive section to the Active section.
8. The server_list.csv file which was included with the Agent Deployment solution must be updated
with remote server names. Access information to establish a connection to those remote servers is
also required (UNIX agents only). The csv file should look as shown in the screenshot below, and
should be called “server_list.csv”. Customer should verify the contents of this file prior to each
agent deployment execution. See the Execution section for encrypting the password put in this file.
9
Windows Specific Prerequisites
1. One windows agent. For Automation Engines installed on windows, the local agent(s) can be used.
For Automation Engines installed on UNIX, a remote Windows agent will need to be installed.
2. PowerShell Remoting must be set up on the server mentioned in step #1 (where the windows agent
was installed) and on all servers where agents will be installed. If using Option #1 below, allow some
time for the group policy to take effect.
 PS Setup Option #1 - Enabling PowerShell via Group Policy:
o http://blog.powershell.no/2010/03/04/enable-and-configure-windows-powershellremoting-using-group-policy/
o

http://windowsitpro.com/powershell/controlling-powershell-execution-policy-settingsdomain
PS Setup Option #2 - Enabling Powershell manually on each server:
o From a command prompt, run ‘winrm quickconfig’ and the output should be as follows:
o
From a command prompt, run ‘powershell’ and run ‘test-wsman <computer name>’.
Output should be as follows if the WinRM service is running.
10
3. If Windows Firewall is turned on, then File and Printer Sharing must be enabled
4. A Windows domain user (i.e. automic) with Administrator privileges which will be used to install the
Agent and Service Manager, as well as run PowerShell commands.
5. Certain ports should be opened on all remote servers. The default ports are listed below, but
customer can use different ports. If using different ports, make sure you update the Automic objects
accordingly. See JOBP.AGENT_DEPLOY.WIN.INSTALL_AGENT_AND_SMGR section below.


2300 – Agent Port
8871 – Service Manager (This should be the same port that’s being used by the Service Manager
on the AE server, otherwise the AE will have problems finding remote agents via a linked service
manager)
UNIX Specific Prerequisites
1. One FTP agent. Keep in mind that Java 1.7 or higher must exist on the server where this agent is
installed. The FTP agent should be configured to allow remote executions. This can be modified in
client 0 by opening the FTP agent object and checking the box on the FTP tab.
2. SFTP must be set up on all remote servers
3. A service account must be set up on all servers that will own and run the Agent and Service Manager
files (i.e. automic), and will be used to FTP the Automic files to the remote servers. It will also need
to be added to the sudoers list to perform the commands below. As mentioned in the Key
Considerations section, sudo with NOPASSWD would be preferred because then it will not echo
the password in clear text in the Automic Job Report, however, the solution will work with a
password to sudo as well.
 mkdir
o When creating directories for the agent and service manager files, the Toolkit will need
privileged access if parts of the directory structure are owned by other users.
 chown -R automic:automic /opt/automic
o Once sudo is used with the mkdir command, the solution changes ownership back to the
user who will own the files
11





chown root /opt/automic/Agents/unix/bin/ucxjlx6
o This command is ONLY used if the customer decides to have the agent binary owned by
root. Root is the preferred option because it allows the customer to run jobs as any
user. However, the customer can opt out of this, in which the binary would be owned by
the user specified during setup of the solution, and jobs can only be run as that user.
chmod 4755 /opt/automic/Agents/unix/bin/ucxjlx6
o This command is ONLY used if the customer decides to have the agent binary owned by
root. Root is the preferred option because it allows the customer to run jobs as any
user. However, the customer can opt out of this, in which the binary would be owned by
the user specified during setup of the solution, and jobs can only be run as that user.
ls -li /proc/$pid/object/
o This command is used only on AIX servers when the solutions needs to determine the
location of a running Service Manager. So the user needs to have privileged access to
get the right process information.
pwdx $pid
o This command is used only on Linux and Solaris servers when the solutions needs to
determine the location of a running Service Manager. So the user needs to have
privileged access to get the right process information.
kill -TERM -$pid
o This command is needed to stop the Service Manager on a server
4. Certain ports should be opened on all remote servers. The default ports are listed below, but
customer can use different ports. If using different ports, make sure you update the Automic objects
accordingly. See JOBP.AGENT_DEPLOY.UNIX.INSTALL_AGENT_AND_SMGR section below.


2300 – Agent Port
8871 – Service Manager (This should be the same port that’s being used by the Service Manager
on the AE server, otherwise the AE will have problems finding remote agents via a linked service
manager)
12
OBJECT SETUP
Folder Structure
All objects needed for the deployment should be included in the transport file that was provided. Once
imported, it will create a folder under the root called AGENT_DEPLOYMENT. The objects that will require
configuration changes are located in the #SETUP folder as seen below.
Agent Groups
HOSTG.AGENT_DEPLOY.JAVA
Required to run the Java functionality of this Toolkit, along with other miscellaneous functions. You will
need to add one Windows or UNIX agent from a server where the Toolkit’s input/config files will be
copied. An ideal agent would be a local agent from the AE, but see the note below for a reason why a
Windows server is preferred.
NOTE: The csv files used/created in this solution will need to be updated with each execution, so it may
be a good idea to place all these files on a Windows server that is easily accessible and also has Excel
installed for faster updating.
13
HOSTG.AGENT_DEPLOY.FTP
Required for UNIX Agent deployments. Add your FTP agent(s) in here.
HOSTG.AGENT_DEPLOY.WIN
Required for Windows Agent deployments. Add the Windows agent here – this is the agent mentioned
in the Windows Specific Prerequisites section. If you add more than one Windows agent here, make sure
all prerequisites have been completed.
Logins
LOGIN.AGENT_DEPLOY.
The credentials for all agents specified in the above Agent Groups (except for the FTP agent) should be
added to this LOGIN object.
14
Workflows
JOBP.AGENT_DEPLOY.UNIX.INSTALL_AGENT_AND_SMGR
Required for UNIX Agent deployments. Update the PRPT objects inside this workflow.
PRPT.AGENT_DEPLOY.UNIX.SETUP


Automic Root Installation Directory – location for the base Automic installation (where the Agents
and Service Manager folder will be created)
Source Root Directory (Agent) – Source folder from the downloaded image where all Agent files are
located. This folder must exist on the server where the FTP agent from the UNIX Specific
Prerequisites was installed.
i.e.
C:\Automic Install Files\V11\Automation.Engine_Image_11_1_15-02-11-1\11\Agents

Source Root Directory (Srv Mgr) – Source folder from the downloaded image where all Service
Manager files are located. This folder must exist on the server where the FTP agent from the UNIX
Specific Prerequisites was installed.

Service Manager Phrase – Identifier that should be used when installing the Service Manager as a
Windows Service. Typically, this is set to the Automic system name.
Default UNIX User – The user that will own and run the Automic Agent and Service Manager files.
This is the same user that should have been set up on all UNIX servers in the UNIX Specific
Prerequisites section. This is also the same user specified for UNIX servers in the server_list.csv file
Default UNIX Group – The user group to which the user above belongs.
UNIX User’s Password – Password of the user above.
Agent Binary Owned by root? – This only applies to UNIX agents. The customer has the option of
having the agent binary owned by root or not. The advantage of root ownership is that jobs can be
run on this agent by any user, which makes this the preferred setup. However, the customer can opt
out of this, in which case the binary is owned by the user specified to do the install/upgrade.
i.e.




C:\Automic Install Files\V11\Automation.Engine_Image_11_1_15-02-11-1\11\ServiceManager
15

NOTE: If the binary is not owned by root, the Toolkit will also set the login_check field in the .ini file
to ‘no’. However, the customer will also be responsible to set ANONYMOUS_FT and
ANONYMOUS_JOB to ‘Y’ in the UC_HOSTCHAR_DEFAULT (or equivalent) variable object in client 0,
as well as restarting the agents after this change. This is a requirement if the agent binary is not
owned by root.
Force Upgrade If Versions Match – In an upgrade situation, if the existing agent’s version matches
the version that it should be upgraded to, then the user can choose whether to keep the agent as is
and cancel the workflow (No), or continue with the upgrade (Yes).
PRPT.AGENT_DEPLOY.UNIX.AGENT_SMGR__INI_CHANGES








Existing .ini File – For agent upgrades, this will give you the option of keeping the existing .ini intact
or creating a new .ini with the config changes on this Prompt Set.
Agent Name – Read only field. Name is left blank so that the server name is used as the Automic
Agent’s name.
System Name – Name given to the Automic system which all agents should point to.
License Class – License class to be used for all agents. Remote agents typically use ‘V’.
Agent Port – The Agent port that was opened during setup in the UNIX Specific Prerequisites
section.
AE Server – Name of the Automation Engine server. Use fully qualified name here, if applicable.
CP Port – One of the Automation Engine server’s CP ports that was set up during the AE installation
in the General Prerequisites section. Make sure the CP port specified here corresponds to the AE
server from the previous field in the case that there are two Automation Engine servers.
SMGR Port – No changes needed here. This will automatically be populated at runtime based on the
port used by the AE Service Manager. The default is 8871.
16
JOBP.AGENT_DEPLOY.WIN.INSTALL_AGENT_AND_SMGR
Required for Windows Agent deployments. Update the PRPT objects inside this workflow.
PRPT.AGENT_DEPLOY.WIN.SETUP







Automic Root Installation Directory – location for the base Automic installation (where the Agents
and Service Manager folder will be created)
Source Root Directory (Agent) – Source folder from the downloaded image where all Agent files are
located. This folder must exist on the server where the Windows agent from the Windows Specific
Prerequisites was installed.
i.e.
C:\Automic Install Files\V11\Automation.Engine_Image_11_1_15-02-11-1\11\Agents
Source Root Directory (Srv Mgr) – Source folder from the downloaded image where all Service
Manager files are located. This folder must exist on the server where the Windows agent from the
Windows Specific Prerequisites was installed.
i.e.
C:\Automic Install Files\V11\Automation.Engine_Image_11_1_15-02-11-1\11\ServiceManager
Service Manager Phrase – Identifier that should be used when running the Service Manager
process. Typically, this is set to the Automic system name.
Default Windows User – An admin user that will be used to install the Automic files and run
PowerShell commands. This is the same user that should have been set up for all Windows servers
in the Windows Specific Prerequisites section. Keep in mind that the agent will run as the SYSTEM
user.
Windows User’s Password – Password of the user above.
Force Upgrade If Versions Match – In an upgrade situation, if the existing agent’s version matches
the version that it should be upgraded to, then the user can choose whether to keep the agent as is
and cancel the workflow (No), or continue with the upgrade (Yes).
17
PRPT.AGENT_DEPLOY.WIN.AGENT_SMGR__INI_CHANGES











Existing .ini File – For agent upgrades, this will give you the option of keeping the existing .ini intact
or creating a new .ini with the config changes on this Prompt Set.
Agent Name – Read only field. Name is left blank so that the server name is used as the Automic
Agent’s name.
System Name – Name given to the Automic system which all agents should point to.
License Class – License class to be used for all agents. Remote agents typically use ‘V’.
Agent Port – The Agent port that was opened during setup in the Windows Specific Prerequisites
section.
AE Server – Name of the Automation Engine server. Use fully qualified name here, if applicable.
CP Port – One of the Automation Engine server’s CP ports that was set up during the AE installation
in the General Prerequisites section. Make sure the CP port specified here corresponds to the AE
server from the previous field in the case that there are two Automation Engine servers.
Job Object – Should be set to 1.
Interpreter Exe – The .exe called when using the interpreter functionality of a Windows Job.
Typically this is set to ‘powershell.exe -NonInteractive -ExecutionPolicy bypass -NoLogo –file’
Interpreter Ext – The extension of the file that is passed on to the interpreter. Typically this is set to
‘ps1’
SMGR Port – No changes needed here. This will automatically be populated at runtime based on the
port used by the AE Service Manager. The default is 8871.
18
Scripts
SCRI.AGENT_DEPLOY.MAIN.INSTALL_MULTIPLE_AGENTS
This is the main script that should be run when installing multiple agents (UNIX and/or Windows).
Update the PRPT inside the Script object.
Important Note – The Toolkit will look for the following directory on the server where the agent in
HOSTG.AGENT_DEPLOY.JAVA exists
PRPT.AGENT_DEPLOY.MAIN_SCRIPT_SETUP



Config Files Directory: A directory that will contain all config files required by the deployment
solution. These files should include:
o AgentDeployTools.jar
o config.ini
o server_list.csv (should be updated every time with the correct list of servers to be affected
during deployment)
o versions.csv – This file can be found in the top level of the unzipped AE image. The image
was downloaded as part of the General Prerequisites.
Perform Initial Check – Set this to TRUE if you want to do a preliminary check before actually
making any changes to the agent on a server. See the Execution section for details on what the
check looks for.
Queue Max Slots – All objects for this solution run in QUEUE.AGENT_DEPLOY. This allows the user
to select the number of slots available in the queue. For multiple agent executions, it is a good idea
to keep this number between 10 and 50. If there happens to be errors on several servers, keeping
this number low makes multiple executions more manageable.
19
NOTE: If you are running a preliminary check, you can increase the Max Slots because the check is
meant to run through all servers without workflows going into a ‘Blocked’ state. Setting the Max
Slots to 100 or higher would be ok.
SCRI.AGENT_DEPLOY.MAIN.INSTALL_ONE_AGENT
This script can be used for installing agents one at a time.
Updating the server_list.csv file is not required when executing this script because it will prompt you for
the server name, custom agent name, and OS type. For UNIX agents, it will also prompt you for the FTP
CONN object name, so you must verify that the CONN object exists for the corresponding remote server
prior to executing this script object.
PRPT.AGENT_DEPLOY.MAIN_SCRIPT_SETUP
Important Note – The Toolkit will look for the following directory on the server where the agent in
HOSTG.AGENT_DEPLOY.JAVA exists


Config Files Directory: A directory that will contain all config files required by the deployment
solution. It can be the same directory set up in the These files should include:
o AgentDeployTools.jar
o config.ini
o server_list.csv (No need to update this file if using this Script object because you will be
prompted for the server name and OS type before execution)
o versions.csv – This file can be found in the top level of the unzipped AE image. The image
was downloaded as part of the General Prerequisites.
Perform Initial Check – Set this to TRUE if you want to do a preliminary check before actually
making any changes to the agent on a server. See the Execution section for details on what the
check looks for.
20

Queue Max Slots – All objects for this solution run in QUEUE.AGENT_DEPLOY. This allows the user
to select the number of slots available in the queue. For multiple agent executions, it is a good idea
to keep this number between 10 and 50. If there happens to be errors on several servers, keeping
this number low makes multiple executions more manageable.
NOTE: If you are running a preliminary check, you can increase the Max Slots because the check is
meant to run through all servers without workflows going into a ‘Blocked’ state. Setting the Max
Slots to 100 or higher would be ok.
21
EXECUTION
Update ‘server_list.csv’
General
This file was provided with the Agent Deployment solution. It can include servers that need new agents,
as well servers with an agent requiring an upgrade. See below for special steps to retrieve a list of
existing Automic agents for upgrades.
Important Note – The Toolkit will look for this file on the server where the agent in
HOSTG.AGENT_DEPLOY.JAVA exists



UNIX servers will require Host name, OS type (UNIX), and custom agent name (if applicable), along
with connection information such as User, Password, User Group, Protocol (will always be SFTP),
and Port (will always be 22). Per execution of the Toolkit, the user credentials for all UNIX servers
should be the same
Windows servers only require the Host name, OS type (WINDOWS), and custom agent name (if
applicable). The other fields can be populated with ‘na’.
Sample CSV file:
Encrypting A Password
For customers who do not want the password in the csv file to be in clear text, an encryption tool has
been provided with the java program (AgentDeployTools.jar).
From a command line, change directory to the location where the jar file was copied. Run the following
command:
java –jar AgentDeployTools.jar Encrypt <Your Password>
Sample run:
22
The solution will automatically add the two dashes (--) at the beginning of the encrypted password. Copy
this password into the csv file for the UNIX servers. Make sure you include the two dashes because the
solution detects an encrypted password by those characters.
Creating an Existing Agent Upgrade File
A Script object (SCRI.AGENT_DEPLOY.CREATE_UPGRADE_AGENT_LIST_CSV) is included with the Toolkit
under the #SETUP folder that can be used to create a csv file of the existing agents in your Automic
system.
The csv file created will be in the same format as the server_list.csv, except it will also include the
version of the agent and whether or not the agent is up or down. The Host column will contain the IP
address of the agent server and not the hostname.
To use this object, update the Prompt Set:


OS Type: You can specify which type of existing agents should be included in the csv file.
Filename and Path: This is the path and name of the csv file that should be created by the script
object. This file will be created on the server where the agent in HOSTG.AGENT_DEPLOY.JAVA exists.
It’s a good idea to name this file something other than server_list.csv because that name is used for
the input file when deploying multiple agents.
23


If File Exists: You can choose from three options when running this script. You can abort the file
creation, you can overwrite the file if it exists, or you can append the results to an existing file.
Active Only: The user can choose to see all agents or just the ones that are up and running. Keep in
mind that the Toolkit can only upgrade running agents, but the ALL option lets you see which agents
need to be started up before upgrading.
Sample upgrade csv file:
Update ‘versions.csv’ (if needed)
The solution compares the current agent version to the versions listed in this file. It can be found in the
top level directory of the downloaded AE image. This file should be added to the configuration directory
specified in the Prompt Set of SCRI.AGENT_DEPLOY.MAIN.INSTALL_MULTIPLE_AGENTS and
SCRI.AGENT_DEPLOY.MAIN.INSTALL_ONE_AGENT.
IMPORTANT: It should be updated every time you install/upgrade agents to a new version of Automic.
Update ‘config.ini’ (if needed)
This file was provided with the Agent Deployment solution. It should only have to be modified upon
initial setup
Important Note – The Toolkit will look for this file on the server where the agent in
HOSTG.AGENT_DEPLOY.JAVA exists
24







AEHostnameOrIp – Name or IP address of the AE server. Use fully qualified name
AECPPort – Corresponding CP port of the AE server specified in previous field
AEClientToConnect – Client in which the Agent Deployment objects were imported
AEUserLogin – Name of a USER object with Admin privileges that exists in the client from the
previous field
AEDepartment – Department of the user specified in previous field
AEUserPassword – Password of the user specified in previous field
AEMessageLanguage – Leave this as ‘E’. Does not affect agent processing.
Verify Information in All Prompt Sets
IMPORTANT: You should verify all Prompt Sets prior to each execution to ensure the right settings are
being used.
When running the Toolkit for multiple agents, the Prompt Set information updated during object setup
will apply to all agents. Because of this, it is recommended to install/update your agents in groups.
For example, one group of UNIX agents might be installed/upgraded with a specific user, and another
group of might be installed with a different user. Or one group will keep the existing .ini file when
upgrading, and another group will replace the existing .ini file.
Executing the Solution
General
Two script objects are provided with this solution under the AGENT_DEPLOYMENT/#SETUP directory.
One will allow you to deploy one agent at a time, and the other allows you to deploy multiple agents
from a server list you provide.
One Agent:
SCRI.AGENT_DEPLOY.MAIN.INSTALL_ONE_AGENT
Multiple Agents:
SCRI.AGENT_DEPLOY.MAIN.INSTALL_MULTIPLE_AGENTS
Preliminary Check
With this solution, an option is built in to allow the user to run an initial check on all servers before
actually making any changes. You can choose this option on the Prompt Set of the script objects during
execution (By default, this is turned off). It is highly recommended to run the preliminary check prior to
installing/upgrading your agents. It will retrieve the necessary information it needs to determine if it can
proceed with the agent installation/upgrade on each server. These checks are done during normal
execution as well, however, the difference is that the preliminary check will end the workflow before
changes are made to the target server.
25
Performing a preliminary check looks for the following things:
 Connectivity to the server
 Ability to retrieve OS, architecture info, and hostname
 Compare agent versions (Takes the ‘Force upgrade if versions match’ setting from the workflow
Prompt Set into consideration)
 Determine whether it will be a new installation or an upgrade
 Verify agent is up and running if it’s an upgrade
 Look for a running Service Manager, and if it exists, be able to determine its location on the
filesystem.
The results of the check will be saved to a .csv file with a naming convention of
‘initial_check_<Date:YYMMDD>_<Time:HHMMSS>. The file will be saved to the config directory that was
specified in the script object’s Prompt Set. Based on the output, the customer can then troubleshoot any
issues found or make the required changes to make the execution run smoothly. They can also update
their server list with the ones that are ready to deploy, as some servers may have scenarios that are not
supported by this solution.
NOTE: It may be necessary for the customer to run the preliminary check a few times to get the most up
to date information, since the check will stop processing on a server at the first error it encounters.
IMPORTANT: Even after completing a preliminary check, it is a good idea to test the solution on a few
agents before executing on an entire list of agents. Once you have installed/upgraded a few agents, you
should also verify that they are active in Automic and that you can run a test job on them.
Sample check results:
The order of the columns is similar to the server_list.csv file. This was done so that you can copy rows
from this file into the server_list.csv when you are ready to begin the actual execution. You will need to
add in this missing column details, if applicable.
Checking status of agent installation/upgrade
The status of each agent’s deployment can be monitored in the Activities window, however, a variable
object is also created upon execution of either script object above to provide general status for each
agent being installed/upgraded. This was mainly intended for getting a quick status check on the agent
deployment. For detailed status, refer to the Reports for the objects executed.
These variable objects can be found in the AGENT_DEPLOYMENT\PAST_RUNS folder. An object will be
created for the script execution with the following naming convention:
26
Normal execution:
VARA.AGENT_DEPLOY.<RUN_ONE|RUN_ALL>.<Workflow_Run_Id>.YYMMDD.HHMMSS
Preliminary Check:
VARA.AGENT_DEPLOY.#__CHECK_ONLY__#.<RUN_ONE|RUN_ALL>.<Workflow_Run_Id>.YYMMDD.HHMMSS
Below is a description and example of the information contained in the variable object.
Key = Name of the server where agent is being installed/upgraded
Value 1 = General status of where the deployment is currently in the workflow.
Value 2 = Run ID of the workflow installing/upgrading the agent.
Value 3 = Whether the deployment is a new install or an upgrade.
Value 4 = Whether or not a service manager was found and linked to the agent.
Value 5 = Status of how the service manager config files were updated.
27