Upgrading the Continuous Optimization Agent

A  Agent collects data from the managed systems in your environment. After collecting data, the Agent transfers it to the Gateway Server. You can upgrade the  Agent using the wizard or silently.

Before you begin

Make sure that you have upgraded the Remote ETL Engine and the Gateway Server before upgrading the  Agent. 

For information about how to upgrade the Remote ETL Engine and Gateway Server, see Upgrading-the-Remote-ETL-Engine and Upgrading-the-Gateway-Server. 

To prepare to upgrade the  Agent

On Windows

  • Verify that the user account for upgrading the  Agent has administrator rights. 
  • We recommend that you configure the Terminal Services on systems to prevent the installer from deleting the temporary folder while it exits the installation. Make sure that the installer does not use temporary folders for each session.

On UNIX and Linux

  • Make sure that you are using a non-privileged and non-root user account for upgrading the  Agent.

  • If you are upgrading the  Agent on a Ubuntu Linux system, make sure that the libxtst6 package is installed.

    To install the libxtst6 package

    1. Download the package from Ubuntu packages. 

    2. Run the following command:
      dpkg -l | grep -i libxtst6

You must upgrade the  Agent on each managed system from which you want to collect data. You can use one of the following upgrade methods:

  • Shell script: You can upgrade the Agent by using the shell script. The script uses the AgentSilentInstallOptions.txt file, which contains the parameters used for configuring the Agent.
  • Docker container: You can upgrade the Agent by using a Docker container. The installation involves loading and running the Docker image on a Docker host. When you run the Docker image, the Docker container is created, and the Agent within the container is started. The Agent starts collecting the system-level metrics from the Docker host. The Docker host can be in an on-premises environment or a cloud environment, such as AWS, Azure, or Google Cloud Platform.

To upgrade the  Agent using a shell script

To upgrade the Agent on Windows systems, make sure that you open the command prompt as an administrator for running the commands.

  1. Log in to the managed system where you want to upgrade the  Agent:
    • (Windows) as a user with administrator privileges.
    • (UNIX and Linux) as root or non-root user.
  2. From the Administration > System > Downloads page, select the platform and click Download.
  3. Extract the  Agent installer files to a temporary directory.
    • (Windows) Extract  TSCO_Agent_ver<version>_MSwindows.zip

    • (UNIX and Linux) Run the following command:
      tar -xvzf TSCO_Agent_ver<version>_<platform>_<architecture or image>.tar.gz
      Example: 

      tar -xvzf TSCO_Agent_ver25.1.02_Linux_x86-64.tar.gz
      tar -xvzf TSCO_Agent_ver25.1.02_Solaris_SPARC.tar.gz

  4. (Optional) To change the default values of the installation properties, complete these steps:
    1. Navigate to the directory that contains the extracted files.
    2. Open the AgentSilentInstallOptions.txt file.

    3. Update values of the required parameters.

       

      Parameter name

      Description

      installLocation

      Retain the following default installation directory path or type a new path:

      • (Windows) C:\Program Files\BMC Software\Patrol3
      • (Linux) /opt/bmc/Patrol3

      Examples: 

      • (Windows) installLocation=C:\Program Files\BMC Software\Patrol3
      • (Linux) installLocation=/opt/bmc/Patrol3

      (UNIX and Linux) 

      BPA_USER

      (Optional) Accept or override this default value.The AgentSilentInstallOptions.txt assigns a default value to this parameter.To override this value, type a username for installing the 

       Agent. Specify a non-root username.Example: 

      BPA_USER=sam

      (Windows) PERFORM_AGENT_START_WINDOWS

      Specify whether you want to start the 

       Agent after installing.Default value: TrueExample: 

      PERFORM_AGENT_START_WINDOWS=True

      (UNIX and Linux) 

      PERFORM_AGENT_START_UNIX

      Specify whether the installer should start the 

       Agent at the end of the installation.Default value: TrueExample: 

      PERFORM_AGENT_START_UNIX=True

      PERFORM_AGENT_ENABLE_HISTORY

      Specify whether you want to enable the collection of historical data.Default value: TrueExample: 

      PERFORM_AGENT_ENABLE_HISTORY=True

      PERFORM_AGENT_HISTORY_REPOSITORY

      Type a directory to store the collected historical data. Default value:
      (Windows) C:\Program Files\BMC Software\Patrol3\BEST1\<version_number>\History(UNIX and Linux) /opt/bmc/Patrol3/perform/historyExample:

      PERFORM_AGENT_HISTORY_REPOSITORY=C:\Program Files\BMC Software\Patrol3\BEST1\25.1.00\History

      (UNIX and Linux) 

      PERFORM_AGENT_COLLECT_REPOSITORY

      Type a directory path to store the data collected daily.Default value: /opt/bmc/Patrol3/perform/collectExample: 

      PERFORM_AGENT_COLLECT_REPOSITORY=/opt/bmc/Patrol3/perform/collect

      (Windows) 

      PERFORM_AGENT_MIGRATION

      Specify whether you want to migrate old configuration files of 

       Agents.Default value: TrueExample: 

      PERFORM_AGENT_MIGRATION=True

      PERFORM_AGENT_PORT

      Type the port number to be used by the 

       Agent.Default value: 6767Example: PERFORM_AGENT_PORT=6767

      PERFORM_INVESTIGATE_PORT

      Type the port number to be used by the Investigate tool.Default value: 6768Example: PERFORM_INVESTIGATE_PORT=6768

      PERFORM_AGENT_SERVICE_PORT

      Type the port number to be used by the Agent service.Default value: 10128Example: PERFORM_AGENT_SERVICE_PORT=10128

      (UNIX and Linux) PERFORM_CREATE_DEFAULT_LINK

      Specify whether you want to create a default link.Default value: TrueExample: PERFORM_CREATE_DEFAULT_LINK=True

      PERFORM_PROCESS_LENGTH

      Type the process command length that the Agent must collect.Default value: 2048Other possible values are 4096, 8192, 16384, and 32768.Example: 

      PERFORM_PROCESS_LENGTH=2048

      PERFORM_SECURITY_CONFIGURATION_TYPE

      Type Basic or Advanced for the security level that you want to use for communication between the Gateway Server and the Application Server. Use Advanced when a direct network connection does not exist between the Agent and the Gateway Server.Default value: BASICExample: 

      PERFORM_SECURITY_CONFIGURATION_TYPE=BASIC

      (UNIX and Linux)

      PERFORM_UNIX_MIGRATION

      Specify whether you want to upgrade the existing version of the 

       Agent if detected.Default value: TrueExample: 

      PERFORM_UNIX_MIGRATION=True

      (UNIX and Linux) 

      PERFORM_UNIX_UNINSTALL

      Specify whether you want to uninstall the existing version of the 

       Agent if detected.Default value: FalseExample: 

      PERFORM_UNIX_UNINSTALL=False

      PERFORM_AGENT_IP_TYPE

      Type a number that indicates your preference for the protocol - IPv6 or IPv4.Default value: 46. This number indicates that the IPv6 protocol must be used only when the IPv4 protocol is not available.To force use of IPv6, type 64.Example: 

      PERFORM_AGENT_IP_TYPE=46

      PERFORM_SSLCONF_SECURITY_LEVEL

      Defines the parameters that need to be enabled in the TLS configuration.Default value if not set: SOCKCOMM_SSL_NONEValid values:

      • SOCKCOMM_SSL_NONE: TLS is Disabled
      • SOCKCOMM_TLSv1_3: Use TLSv1_3
      • SOCKCOMM_SSL_SKIP_HOST_CHECK: Client skips common name check against hostname
      • SOCKCOMM_SSL_ALLOW_EXPIRED_CERTIFICATE: Allow expired certificates
      • SOCKCOMM_SSL_NO_FALLBACK: Client does not fallback to plain sockets

      To specify more than one parameter for SSL configuration, separate them with "|" (pipe) symbol without any spaces in between.Example: 

      PERFORM_SSLCONF_SECURITY_LEVEL=SOCKCOMM_TLSv1_3|SOCKCOMM_SSL_SKIP_HOST_CHECK

       

5. Run the following command to start the upgrade:

  • (Windows) <path_to_install.bat>\install.bat -DOPTIONS_FILE=<path_to_AgentSilentInstallOptions.txt>
    Example: C:\Users\Administrator\Downloads\installer\install.bat -DOPTIONS_FILE="C:\AgentSilentInstallOptions.txt"
  • (UNIX and Linux) ./install.sh -DOPTIONS_FILE=<path_to_AgentSilentInstallOptions.txt> 
    Example: ./install.sh -DOPTIONS_FILE=/installer/AgentSilentInstallOptions.txt

A confirmation message is displayed indicating that the upgrade is completed.

6.(UNIX and Linux) Run the following command as a root user to configure the Agent. Perform this step only if you installed the Agent as a non-root user.

  1. Change to the root user.
  2. Change to the installation directory and run the following command:
    ./b1config<version>.sh
    where version indicates the version of the installed  Agent.

To verify the status of the upgraded Agent

On Windows

  1. At the command prompt, enter services.msc

  1. Check whether the BGS_SDService service is running.

    Important

    The Microsoft Windows agent binary files under the bgs\bin and bgs\UMXscripts\bin directories have a digital signature.

On UNIX and Linux

Run this command to make sure that the agent daemon service (/etc/bgs/SD/bgssd.exe -d /etc/bgs/SD -s) is running as a non-root user:
ps -ef | grep bgs

You can update values of the Agent configuration parameters whenever required. For more information, see Configuring-the-Continuous-Optimization-Agents.{{/confluence_layout-section}}
{{/confluence_layout}}

Data URI image
)))

To upgrade the  Agent using a Docker container

  1. Log in as a root user to the Linux system where you want to upgrade the Agent.
  2. Change to the directory containing the Agent installer files that you downloaded from Downloads page (Administration > System > Downloads).
  3. Run the following command to load the zipped Docker image to a local repository:
    docker load -i tsco-agent-linux-x86_64_<version>.tar.gz
    Example:
    docker load -i tsco-agent-linux-x86_64_25.1.02.0.00.tar.gz
  4. Run this command to verify that the Docker image is loaded:
    docker images
    Example:
    $ docker images | grep tsco-agent
    Sample output: bmcsoftware/tsco-agent-linux-x86_64   25.1.02.0.00   7bbb7a3fae1d   29 hours ago   200MB

  5. Run the following command to create a container from the image and start the Agent within the container:

    docker run -d --pid=host --network=host --ipc=host --privileged -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace bmcsoftware/tsco-agent-linux-x86_64:<version>

    Example:

    docker run -d --pid=host --network=host --ipc=host --privileged -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace bmcsoftware/tsco-agent-linux-x86_64:25.1.02.0.00

    Argument

    Used to

    Example syntax of the Docker run command

    --name <value>

    Provide a name to a Docker container. You can use this name in other Docker commands instead of docker ID. You cannot start a new container with a similar name in the following scenarios:

    • A Docker container with the same name is already running.
    • An instance of a Docker container that uses the same name is available in the Docker container repository.

    We recommend using a container name such as tsco_agent.

    To start a container with the tsco_agent name that is already in use, do the following steps:

    1. Stop the Docker container:
      $ docker stop tsco_agent
    2. Remove the stopped container.
      $ docker rm tsco_agent

    You can now start a new container instance with the tsco_agent name.

    docker run --name tsco-agent -d --pid=host --network=host --ipc=host --privileged 
    -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace bmcsoftware/    tsco-agent-linux-x86_64:25.1.02.0.00

    --restart=always

    Restart a running Docker container after rebooting the docker host.

    docker run --name tsco-agent --restart=always -d --pid=host --network=host
    --ipc=host --privileged -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace 
    bmcsoftware/tso-agent-linux-x86_64:25.1.02.0.00

    where -v tsco-agent-vol is mounted in the container as the /usr/adm/best1_agent_workspace directory. This directory is used for storing data, logs, and state information. If you do not specify this parameter, agent data and logs are stored within the container instead of the volume on the host. 
    We also recommend adding the following arguments to the Docker run command:

  6. (Optional) Configure the Agent history by adding one of the following arguments to the Docker run command: 
    [ -H e|d|D ]

    Argument

    Example syntax of the Docker run command

    Result of running the Docker run command

    - H e

    docker run --name tsco-agent --restart=always -d --pid=host --network=host --ipc=host --privileged
    -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace 
    bmcsoftware/tsco-agent-linux-x86_64:25.1.02.0.00 - H e

    The Agent history is enabled, which is the default setting.

    - H d

    docker run --name tsco-agent --restart=always -d --pid=host --network=host --ipc=host --privileged
    -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace
    bmcsoftware/tsco-agent-linux-x86_64:25.1.02.0.00 - H d

    The Agent history is disabled.

    - H D

    docker run --name tsco-agent --restart=always -d --pid=host --network=host --ipc=host
     --privileged -v /:/host:ro tsco-agent-vol:/usr/adm/best1_agent_workspace 
    bmcsoftware/tsco-agent-linux-x86_64:25.1.02.0.00 - H D

    The Agent history is disabled and the old history files are deleted. You can use this option to remove the old history files after upgrading the Agent.

  7.   (Optional) Configure TLS security level by adding the following argument to the Docker run command: [ -S values ]

    Argument

    Example syntax of the Docker run command

    Result of running the Docker run command

    -S <value1|value2>

    docker run -d --pid=host --network=host --ipc=host --privileged -v /:/host:ro
    -v tsco-agent-vol:/usr/adm/best1_agent_workspace
    bmcsoftware/tsco-agent-linux-x86_64:25.1.02.0.00 -s 10138 -a 64111 -d 64112
    -S "SOCKCOMM_TLSv1_3|SOCKCOMM_SSL_SKIP_HOST_CHECK|SOCKCOMM_SSL_ALLOW_EXPIRED_CERTIFICATE"

    Enables TLS on Agent using options provided along with "-S".

    The options for "-S" argument are the same as for PERFORM_SSLCONF_SECURITY_LEVEL.

  8. Run this command to check the status of the Agent process:
    ps -ef | grep bgsagent

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*