Automic Agent Deployment and Upgrade Toolkit. How-To Documentation

Transcription

1 Automic Agent Deployment and Upgrade Toolkit How-To Documentation

2 1 AUTOMIC AGENT DEPLOYMENT AND UPGRADE TOOLKIT 1.1 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 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 Toolkit 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. 1.2 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 Toolkit 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. 1.3 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 2

3 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 1.4 Compatibility The Agent Deployment and Upgrade Toolkit must be installed with an Automation Engine that is running V10 or higher. The Toolkit has been tested with upgrading agents that are currently on V6 and higher. Currently, it can only be used to install and upgrade Windows and UNIX 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 3

4 1.5 Key Considerations / Limitations The following scenarios should be considered before using this Toolkit: 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 Toolkit. This is why it is important to check all Promptsets before an execution, and also a good idea to execute the Toolkit 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. o IMPORTANT: If upgrading UNIX agents from V6 / V8, you should check whether the agent binaries and INI filenames are in uppercase or not. If they are, you should NOT choose the option to keep the existing INI file because later versions of Automic (V9 and later) use lowercase letters for all UNIX agent files. Keeping the existing file will cause issues during the upgrade and also when trying to start the agent. 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 Toolkit. The Toolkit 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 Toolkit 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 Toolkit has no way of determining the root installation path. o EXCEPTION: For Automic V6 agents, the default agent installation location is an Executor folder as opposed to an Agent folder, which means the Toolkit will search for Executor or Executors (case insensitive) in the agent s install bin path. Multiple Agents on One Server This Toolkit 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 Toolkit for new installations and upgrades. However, the customer MUST remember to include the custom agent name when running the Toolkit. If not, in the case of new installations, the Toolkit will install a new agent using the hostname; in the case of upgrades, the Toolkit 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 4

5 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 Toolkit will not be able to continue because it does not have a way of detecting any details for that Service Manager. The Toolkit can only scan for a Service Manager via Automic using an existing agent. 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 Toolkit 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/backed up in place If an existing agent is located in a directory other than what was specified for the Automic root installation directory' during setup, then it will upgraded in the same directory. It will not be moved to the directory specified during setup. There is no option at the moment to specify a new installation directory for the agent during an upgrade. All upgrades will also back up the old agent s files/folders to a directory with naming convention (Agent_Backup_<Run ID>_<Date:YYMMDD>_<Time:HHMMSS>). Keep in mind that when the workflow reaches the job (JOBS.AGENT_DEPLOY.FTP_UNIX.AGENT COPY_AND_UNTAR_FILES for UNIX, or JOBS.AGENT_DEPLOY.WIN.AGENT COPY_FILES for Windows), it will always create a backup of the old files if it s doing an upgrade. o EXCEPTION: For Automic V6 Windows agents, the bin path is hardcoded in the agent s ini file (i.e. C:\UC4\Executor\windows\bin), which means the database will have this value as well. If you used this default installation path, then disregard this exception. If not, then it is important to note that the upgrade will move the agent and Service Manager to this path, but the backup of old agent files/folders will remain in the old installation directory. A work around for this would be to update the following lines in each V6 agent s ini file as follows, restart the agents, and then upgrade using this Toolkit. However, this process may not be an easy change for some customers. Defaults: Change paths to match where you installed the agent: 5

6 Rollback Unavailable Rolling back to a previous backup made by the Toolkit is not available. 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), renewing the transfer key via System Overview in client 0, and finally starting the agent via the Service Manager. If there was no Service Manager to start with, the agent will have to be started manually. 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 Toolkit 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 Toolkit (see the UNIX Specific Prerequisites section for details). Sudo with NOPASSWD set for those commands is preferred. The Toolkit 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 Toolkit will check to see if a Service Manager is installed and linked to the AE system. NOTE: Service Manager must be running for the Toolkit to detect it. If not, a Service Manager will be installed. If the Toolkit finds one or more Service Managers already installed, but cannot determine one that is linked to the AE system, then the Toolkit 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 Toolkit. 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 o Agent servers with Service Manager Already Running If the port number on the AE and agent server do not match, then this Toolkit will be unable to find the Service Manager on the agent server, and the workflow will block. Agent servers with no Service Managers Running In this case, the Toolkit 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 Toolkit cannot find the service manager running on the AE s SMGR port, then the workflow will block. The reason for this is because the Toolkit is unable to determine which service manager belongs to the AE system. 6

7 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. 1.6 Disclaimer The Agent Deployment and Upgrade Toolkit is offered as no-charge community toolkit. The Toolkit is distributed AS IS and without any express or implied warranty. Automic makes no representations that the Toolkit (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 Toolkit 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 Toolkit and any changes/extensions remain the sole property of Automic. 7

8 2 PREREQUISITES 2.1 General 1. Read all information provided in Section 1.5 Key Considerations / Limitations before using this Toolkit. There may be a scenario that applies to your environment which might prevent you from installing/upgrading agents using this Toolkit. Consult with Automic if you have any questions or uncertainties. 2. Download full AE image from Automic download site. This should be the version that your AE is currently on or will be upgraded to, and also the version that your agents will be on. 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 CP Ports WP Ports 8871 Service Manager 2300 Agent Port 4. Automation Engine installed (or upgraded) to the version that the agents will be moving to. The AE s local OS agent should also be upgraded. Make sure that your license supports the type and number of agents to be deployed. If you have an Active-Active setup, then both Automation Engines should be upgraded along with their corresponding local OS agent. 5. For Automation Engines installed on UNIX, verify that the local OS agent(s) has the following line updated in its INI file. If an update is needed, a restart of the agent will be required afterwards. The following line should be updated so that the name of the binary matches the name of the particular agent you installed. For example, change ucxj???m to ucxjlx6m for the x64 Linux agent. 6. SQLVAR_INTERNAL must be set to YES and VAR_SECURITY_LEVEL must be set to 3 in the UC_SYSTEM_SETTINGS VARA object in client A transport file has been included with the Toolkit that contains all the objects needed. Use DB Load to load these objects into the client of your choice. The transport file will have the naming convention of Transport_AgentDeploymentToolkit_v#.#_YYYYMMDD.txt 8

9 8. Import HSTA.AGENT_DEPLOY into folder of your choice in client 0. Export file should be included with Toolkit. The purpose of this object is to assign installed/upgraded agents to the client in which you loaded the Agent Deployment objects in the previous step, so that you can see the agents start/stop as they are being installed/upgraded. You can also use this object to assign the installed/upgraded agents to another client, but keep in mind that the filter used in the HSTA object considers ALL Windows AND Unix agents. If you would like to use a different filter, you can create another HSTA object. Once imported, open the object and on the Authorizations tab, select all check boxes for the client(s) where you would like to assign the installed/upgraded agents. Afterwards, open System Overview, click Agent Assignment in the left panel, and drag the HSTA object in the Inactive section to the Active section. 9. Create a directory on the AE server and copy the following files to it. We will reference this directory later in the Object Setup section. If you have an Active-Active setup, then choose one of those AE servers to create this directory. AgentDeployTools.jar (included with the Toolkit) config.ini (included with the Toolkit) server_list.csv (included with the Toolkit) versions.csv This file can be found in the top level of the unzipped AE image that you downloaded in Step #1 uc4.jar (included with the Toolkit). The included file is compatible with AE version 12 and earlier. For future versions of the AE, you will need to update this file. The latest uc4.jar file can be found in the downloaded AE image under the ApplicationInterface folder. jasypt lite.jar (included with the Toolkit). opencsv jar (included with the Toolkit). 10. Java 1.7 or higher (JRE or JDK) should be installed on the AE server(s) (if not already done as part of the AE installation). 11. Agents to be upgraded must be up and running. 2.2 Windows Agent Specific Prerequisites 1. A Windows agent is required to perform the install/upgrade on all your Windows agents. For Automation Engines installed on windows, a local agent can be used. For Automation Engines installed on UNIX, use one of the existing Windows agents, but make sure you manually upgrade it first. 2. A Windows domain user (i.e. automic) with Administrator privileges is required, which will have access to the Windows server from Step #1 and to all Windows agent servers. 3. PowerShell Remoting must be set up on the server mentioned in step #1 (where the windows agent exists) and on all servers where agents will be installed/upgraded. If using Option #1 below, allow some time for the group policy to take effect. 9

10 o PS Setup Option #1 - Enabling PowerShell via Group Policy: o PS Setup Option #2 - Enabling Powershell manually: o On each server: From a command prompt, run powershell and then enablepsremoting. Answer A to all questions. Output should be as follows: o Test the connection from server in Step #1 to a remote agent server: From a command prompt, run powershell and run test-wsman <remote_agent_server>. Output should be as follows if PSRemoting was setup correctly. 4. Verify that firewalls and/or anti-virus programs are not blocking access to the servers and not blocking write access to the install directories. 5. Certain ports should be opened on all Windows agent 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 Agent Port 10

11 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 the agent via a linked Service Manager) 2.3 UNIX Agent Specific Prerequisites 1. An FTP agent is required to perform the install/upgrade on all your UNIX agents. 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. NOTE: The.ssh\known_hosts file will need to be set up to allow the FTP agent to SFTP to the agent servers. If the FTP agent is installed on Windows, you can create a blank \.ssh\known_hosts file (default location is typically C:\) and the FTP agent will update the file as needed. 2. SFTP must be set up on all UNIX agent servers. 3. A service account must be set up on all agent 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 agent 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 Automic FTP jobs echo all commands (including the password which is piped to sudo) to the Automic Job Report. 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 Toolkit changes ownership back to the user who will own the files 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 Toolkit, and jobs can only be run as that user. See the PRPT.AGENT_DEPLOY.UNIX.SETUP section for settings on opting out of root ownership. 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 Toolkit, and jobs can only be run as that user. See the PRPT.AGENT_DEPLOY.UNIX.SETUP section for settings on opting out of root ownership. ls -li /proc/$pid/object/ o This command is used only on AIX servers when the Toolkit needs to determine the location of a running Service Manager. The user needs to have privileged access to get the right process information. 11

12 pwdx $pid o This command is used only on Linux and Solaris servers when the Toolkit needs to determine the location of a running Service Manager. 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 agent 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 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 the agent via a linked Service Manager) 12

13 3 OBJECT SETUP 3.1 Folder Structure All objects needed for the deployment should be included in the transport file that was loaded during the General Prerequisites. 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. 3.2 Agent Groups HOSTG.AGENT_DEPLOY.AE Required to run the Java functionality of this Toolkit, along with other miscellaneous functions. You will need to add the local AE agent on whose server you created the directory in step #7 of the General Prerequisites HOSTG.AGENT_DEPLOY.FTP Required for UNIX Agent deployments. Add the FTP agent in here that was setup in step #1 in the UNIX Prerequisites section. 13

14 3.2.3 HOSTG.AGENT_DEPLOY.WIN Required for Windows Agent deployments. Add the Windows agent in here that was setup in step #1 of the Windows Prerequisites. For customers who have their Automation Engine on Windows, this agent will be the same agent specified in HOSTG.AGENT_DEPLOY.AE. 3.3 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. 3.4 Workflows JOBP.AGENT_DEPLOY.UNIX.INSTALL_AGENT_AND_SMGR Required for UNIX Agent deployments. Update the PRPT objects inside this workflow. 14

15 PRPT.AGENT_DEPLOY.UNIX.SETUP Automic Root Installation Directory This is where the root Automic installation will be located on the agent server (where the Agents and Service Manager folder will be created). For example, /opt/automic Source Root Directory (Agent) Source folder from the downloaded AE image where all Agent files are located. This folder must exist on the same server as the FTP agent that was setup during step #1 of the UNIX Specific Prerequisites i.e. C:\Automic Install Files\V11\Automation.Engine_Image_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 same server as the FTP agent that was setup during step #1 of the UNIX Specific Prerequisites i.e. C:\Automic Install Files\V11\Automation.Engine_Image_11_1_ \11\ServiceManager Service Manager Phrase Identifier that should be used when running the Service Manager. Typically, this is set to the Automic system name. i.e. AUTO_DEV 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. This is not a required field. 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 using this setting, in which case the binary is owned by the user specified to do the install/upgrade. NOTE: If the user decides to opt out of root ownership, the Toolkit will also set the login_check field in the agent.ini file to no. However, the customer will be responsible to set ANONYMOUS_FT and 15

16 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. Force Upgrade If Versions Match In an upgrade situation, if the existing agent s version matches the UNIX version found in versions.csv, then this setting allows the user to choose whether or not 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 agent server s hostname is used as the agent name, unless a custom agent name was specified for the particular agent server. System Name Name given to the Automic system which all agents should point to. License Class License class to be used for all agents. All OS agents other than the local AE agent 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. 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 you have an Active-Active setup 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

17 3.4.2 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 This is where the root Automic installation will be located on the agent server (where the Agents and Service Manager folder will be created). For example, C:\Automic Source Root Directory (Agent) Source folder from the downloaded image where all Agent files are located. This folder must exist on the same server as the Windows agent that was setup during step #1 of the Windows Specific Prerequisites i.e. C:\Automic Install Files\V11\Automation.Engine_Image_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_ \11\ServiceManager 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. i.e. AUTO_DEV Default Windows User The domain 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 agent servers in the Windows Specific Prerequisites section. Keep in mind that the agent, once started, 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 Windows version found in versions.csv, then this setting allows the user to choose whether or not to keep the agent as is and cancel the workflow (No), or continue with the upgrade (Yes). 17

18 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 agent server s hostname is used as the agent name, unless a custom agent name was specified for the particular agent server. System Name Name given to the Automic system which all agents should point to. License Class License class to be used for all agents. All OS agents other than the local AE agent 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. 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 you have an Active-Active setup 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

19 3.5 Scripts SCRI.AGENT_DEPLOY.MAIN.INSTALL_MULTIPLE_AGENTS This is the main script that should be run when installing/upgrading multiple agents (UNIX and/or Windows). Update the PRPT inside the Script object PRPT.AGENT_DEPLOY.MAIN_SCRIPT_SETUP Config Files Directory: This should be the full path to the directory created in Step #7 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 Toolkit run in QUEUE.AGENT_DEPLOY. This setting allows the user to select the number of active slots available in the queue. Because a workflow is executed for each agent and only one task is active inside that workflow, there should be 2 active slots for each agent being installed/upgraded. o The default value for this field is 10 which means 5 or less agent installations/upgrades can run in parallel. This is set initially to 10 because the customer should always test this solution on a small set of agents first. To install/upgrade more than 5 agents at a time, the rule of thumb is to set the max slots to twice the number of agents. For example, for 10 agents set the max slots to 20; for 20 agents set the max slots to 40. o While this number can be set to as high as 9999, it is highly recommended to keep it at 50 or lower. You can still add as many agents as you want to the csv file (see Section 5 below), however keeping this number low (50 or lower) allows no more than 25 installations/upgrades to run in parallel and also makes troubleshooting more manageable if errors occur. 19

20 3.5.2 SCRI.AGENT_DEPLOY.MAIN.INSTALL_ONE_AGENT This is the main script that should be used when installing/upgrading agents one at a time PRPT.AGENT_DEPLOY.MAIN_SCRIPT_SETUP Config Files Directory: This should be the full path to the directory created in Step #7 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 This setting does not affect this type of execution because only one agent is being installed/upgraded. 20

21 4 EXECUTION CHECKLIST 4.1 Update server_list.csv This file should be updated when installing/upgrading multiple agents. NOTE: If executing the script SCRI.AGENT_DEPLOY.MAIN.INSTALL_ONE_AGENT, which installs/upgrades an agent one at a time, then there is no need to update this csv file because the user will be prompted for the agent server information, i.e. agent server name, custom agent name, OS type, etc General This file was provided with the Agent Deployment Toolkit. It can include servers that need new agents, as well servers with an agent requiring an upgrade. See Section 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.AE 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). For each execution of the Toolkit, the user credentials for all UNIX servers in this list 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). 21

22 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: The Toolkit 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 Toolkit 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. The results can then be used to populate the server_list.csv file. To use this object, update the Prompt Set: 22

23 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.AE 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. 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: 4.2 Update versions.csv (If Needed) The Toolkit 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 have been added to the directory created in Step #7 of the General Prerequisites. IMPORTANT: It should be updated every time you install/upgrade agents to a new version of Automic. 23

24 4.3 Update config.ini (If Needed) This file was provided with the Agent Deployment Toolkit. It should only have to be modified upon initial setup. It should have been added to the directory created in Step #7 of the General Prerequisites. 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. 4.4 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 in the Object Setup section 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 might be installed with a different user. Or one group of agents will keep the existing.ini file when upgrading, and another group of agents will replace the existing.ini file. 24

25 4.5 Executing the Toolkit General Two script objects are provided with this Toolkit 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 [Highly Recommended] With this Toolkit, 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. 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 agent server. 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 Toolkit. 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 Toolkit 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. 25

26 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 the missing column details, i.e. password information. 4.6 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/Details 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: 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. 26

27 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, or performing the preliminary check. 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