Deploy Agent

The Agent comprises of Scan and Certificate Update agents.

Supported antivirus

By default, IBM PEM supports ClamAV antivirus software, but not included in the IBM PEM image. However, you can use any other antivirus software other than ClamAV and ensure to install it separately on the same machine where the Scan Agent container is running. For more information, see Antivirus extensibility.

Prerequisites

Before running the command, complete the following tasks:
  • Configure the files that are present in your Mount directory.

    For more information, see Configuring the files in Mount directory.

  • In the clamd.conf file, set the ClamAV host IP to the TCPAddr parameter (for example TCPAddr 91.119.227.33) and port to TCPSocket parameter (for example TCPSocket 3310). The clamd.conf file is present under the /etc folder.
  • To run the Scan Agent, configure the value of agent.type=scanagent property.
  • To run certificate update, configure the value of agent.type=certificateupdate property.
  • To run both Scan Agent and certificate update, configure the value of agent.type=scanagent,certificateupdate property. By default, the value is set to scanagent,certificateupdate.

Running the command to deploy the Agent

Run the following command:

  • Docker:
    docker run --name="<container name>" --add-host=<host_name>:<IP address> -v <path to mount files>:/opt/IBM/Resources -v <path to logs>:/opt/IBM/Agent/bin/log -v /etc/localtime:/opt/IBM/localtime:ro -e application="agent" -dt <image name>:<version>
  • Podman:
    podman run --name="<container name>" --add-host=<host_name>:<IP address> -v <path to mount files>:/opt/IBM/Resources -v <path to logs>:/opt/IBM/Agent/bin/log -v /etc/localtime:/opt/IBM/localtime:ro -e application="agent" -dt <image name>:<version>
where, --add-host is optional.
Note: Enter the appropriate parameter values within the angle (<>) brackets.
Important: As the application name is case-sensitive, you must enter the application name in the same case as provided in the run command. For example, application="Agent" is invalid.
Here,
  • <container name> - refers to the user-defined container name.

    If you again use the container with the same name, the docker/podman engine reports that the container with the same name is already in use. In such a situation, you can either delete the container by running the command, docker/podman rm <container name> or use a different container name.

  • <path to mount files> - provide the absolute path of the directory where the mount files are extracted. For the contents of the mount directory, see Mount Directory structure.
  • --add-host=<host_name>:<IP address> - Can add other hosts into the /etc/hosts file of the container by using one or more --add-host flags.
  • <path to logs> - this is the absolute path of the directory in your host machine that is mounted into the container's log path.
  • -v /etc/localtime:/opt/IBM/localtime:ro - synchronizes the container's time zone with the host machine's time zone.
Note: If you configure an API with a hostname, the API call from PEM Partner Repository or PEM Partner Provisioner fails as the application running inside the docker container cannot resolve the hostname. To resolve the hostname, add the hostname mapping by adding --add-host=<host_name>:<IP address> in the docker run command, delete the old container, and create a new container by running the updated docker run command.

Sample run command

  • Docker:
    docker run --name="Agent" --add-host=<host_name>:<IP address> -v /home/MountResource/:/opt/IBM/Resources -v /home/logs/agent:/opt/IBM/Agent/bin/log -v /etc/localtime:/opt/IBM/localtime:ro -e application="agent" -dt registry.ng.bluemix.net/gold/pem:3.5.16
  • Podman:
    podman run --name="Agent" --add-host=<host_name>:<IP address> -v /home/MountResource/:/opt/IBM/Resources -v /home/logs/agent:/opt/IBM/Agent/bin/log -v /etc/localtime:/opt/IBM/localtime:ro -e application="agent" -dt registry.ng.bluemix.net/gold/pem:3.5.16
Note: Here, --add-host is optional.

Log files

Log files help in analyzing and debugging the errors. You can find the log files in the logs directory. For agent-specific error messages, see the Agent_<timestamp>.<version>.log file. For example, Agent_201607210708.0.0.log.

Note: Before starting the container, ensure to back up the container log directory.

Verifying the Docker/Podman run command

To verify whether the Docker/Podman run command is successful, run docker logs <container name> or podman logs <container name> or see the logs directory for more details.

Configuring the properties in Setup.cfg file

Configure the following properties:
  • accept_license
  • proxy_host
  • proxy_port
  • customer_id
  • db_type
  • ssl_connection
  • db_port
  • db_host
  • db_name
  • db_schema
  • db_user
  • db_password
  • db_driver
  • db_max_pool_size
  • db_min_pool_size
  • db_aged_timeout
  • db_max_idle_time
  • db_sslTrustStoreName
  • db_sslTrustStorePassword
  • agent.type
  • agent.jvm_options
  • agent.antivirus_server_host
  • agent.antivirus_server_port
  • agent.no_of_db_connections
  • agent.retry_interval_in_sec
  • agent.max_retry_count
  • agent.com_ibm_vch_identity_security_limit
  • agent.com_ibm_vch_identity_security_level
  • agent.com_ibm_vch_identity_security_count
  • agent.scan_extensibility_class. This is optional. Configure this property, if you are using any other antivirus besides ClamAV.

    For more information, see Antivirus extensibility.

Important:
  • To establish a connection to IBM subscription verification system, you must configure proxy_host and proxy_port.
  • If you run multiple agents simultaneously, during the agent startup, if you encounter the following error (depending on your database), you can safely ignore this error.

    If multiple servers are started with a time delay, you might not encounter this error.

    • For DB2, you might encounter the following error:
      Couldn't acquire next trigger: DB2 SQL Error: SQLCODE=-911, SQLSTATE=40001, SQLERRMC=2, DRIVER=4.21.29 [See nested exception: com.ibm.db2.jcc.am.SqlTransactionRollbackException: DB2 SQL Error: SQLCODE=-911, SQLSTATE=40001, SQLERRMC=2, DRIVER=4.21.29]
        at org.quartz.impl.jdbcjobstore.JobStoreSupport.acquireNextTrigger(JobStoreSupport.java:2864)
    • For Oracle, you might encounter the following error:
      Couldn't acquire next trigger: ORA-08177: can't serialize access for this transaction
 [See nested exception: java.sql.SQLException: ORA-08177: can't serialize access for this transaction]
 at org.quartz.impl.jdbcjobstore.JobStoreSupport.acquireNextTrigger(JobStoreSupport.java:2864)