Installing the Agent for x64 Linux (Java)

Important! These installation instructions apply only to the installation of x64 Linux agents. For installation instructions for other UNIX agents, see Installing the Agent for other UNIX Platforms.

The Java Agents require a JRE (version 11 or higher) to be available. If your system does not have a JRE installation, you can install it in the <Agent>/bin/jre/ folder.

This page guides you through the installation of a Java based x64 Linux Agent in an AE system without using authentication. If you want to use one of the authentications methods available, you need to follow additional installation steps. For more information, see Agent Authentication.

Check the compatibility matrix to see which version is compatible with your system. For more information, see Compatibility Information.

Tip! This page refers only to the manual installation process. If you want instructions on how to install a containerized UNIX agent, see Installing Containerized UNIX Agents.

This page includes the following:

Overview

Each supported UNIX variant has a three-character code which is part of the Agent's file name. In this topic the specific code is replaced by "???."

Jobs scheduled to run on UNIX Agents can include customer-specific scripts. If one of these scripts modifies the LD_LIBRARY_PATH environment variable while the loader is running, the change remains in the shell environment. If the messenger binary runs after that, loading fails and the job execution is aborted. For more information, see Troubleshooting - LD_LIBRARY_PATH Overridden .

Note: You must create an own UNIX user ID for the Automation Engine (default: uc4, Home = /opt/uc4).

The x64 Linux Agent supports sending emails using SMTP and SMTPS. For more information, see Setting Up Email Connections.

Important Considerations

The following sections describe some important topics that you must consider when installing and configuring the Agent.

Shipment of Standard Libraries in UNIX Systems

The standard libraries (libstdc++.so and libgcc_s.so) are no longer part of the Agent, the Service Manager nor the Utilities .tar balls. Now, they are delivered with the offering under External.Resources/unix_libraries/unix_libraries.tar.gz.

Important! If the libraries are not installed properly, the relevant component will not start properly. Therefore, you have to make sure that all standard libraries are available so that the Agent, Utility and/or ServiceManager can used them.

To do so, go to the offering bundle and get the libstdc++.so.6 and libgcc_s.so.1 libraries. Once you have untarred the .tar ball (unix_libraries.tar.gz), you can copy the libraries you got from the bundle to the bin directory of the respective component. You can then use the ln -s ./libstdc++.so.6 command to create symlinks in the bin directory.

Privileged and Unprivileged Mode

The Agent for UNIX operating systems can be installed to run either as a privileged or an unprivileged process. However, the Agent can only operate with full capabilities if it is installed as a privileged process.

You can use three different methods to start the Agent with root privileges:

  1. Start the Agent directly under the user root.

  2. Define root as owner, assign the group in which the start user belongs, set the execute bit for the group and set the SetUID (s-bit) for the Agent file owner.

    Example

    • chown root ucxjlx6

    • chgrp admin ucxjlx6

    • chmod 4755 ucxjlx6

    When using the UNIX platform Agent Solaris, it is not possible to load libraries from custom folders as root unless the Agent is started by root, which means that a regular user with the SetUID flag cannot start the Agent. Therefore, you have to explicitly allow loading libraries from custom folders as root to load the Agent from a custom folder using SetUID. To do so, you can use crle commands. For example, sudo crle -64 -s <agent bin absolute path> -u.

  3. Separation of privileges.

    The Agent uses the user_service program which is responsible for serving requests such as create file, directory, start process and so on to the OS as a different user. It is also responsible for setting the proper security environment for resources such as adapt owner or default permissions. The program is started in the background with the credentials specific to that user. It is started by the Agent only on demand (when required) and remains active until the inactivity timeout is reached.

    The [AUTHORIZATION] section of the Agent's INI file contains the agentUser parameter which is used for downgrading the Agent's process. This means that, after the Agent is started (with higher privileges), it changes its own identity to the user that has been specified in that parameter, so that the listening port(s) are not started and served by the privileged user.

    The Agent always tries to start with separated privileges, if possible. If not, the Agent starts with the same user, without separation of privileges.

    The following rules apply:

    • Rule 1: The Agent is started with the native launcher (./ucxjlx6) using sticky bit (effective UID = 0).

      In this case, the Agent tries to change its identity to the user defined in the agentUser parameter. If the parameter has no definition (default), the Agent changes the effective user ID to the real user ID (separation of privileges).

    • Rule 2: The Agent is started with the native launcher (./ucxjlx6) not using sticky bit.

      In this case, the Agent tries to change its identity to the user defined in the agentUser parameter. If the parameter has no definition (default), the agent’s identity remains unchanged.

      Depending on the definition of the login_Check settings, the functionality might be limited.

    Note: The identity of the agent cannot be changed to user nobody! as this would cause security issues and the Agent would not be able to connect to the Automation Engine.

Why are root privileges needed?

The UNIX Agent executes a variety of tasks under control of the Automation Engine. These tasks must be executed under users that are assigned to the tasks. To be able to start tasks as users other than the UNIX Agent start user, to do inter-process communications as users other than the UNIX Agent start user, or to access files as a user other than the UNIX Agent start user, the UNIX Agent requires root privileges to be able to switch the user context.

Which tasks are performed for which users?

In the Automation Engine, jobs, file transfers, file events, or even various Automation Engine scripting language commands are defined for certain users. The user credentials are defined in Login objects in the Automation Engine.

What are the limitations if the UNIX Agent is operated in unprivileged mode?

You operate in unprivileged mode when the Agent has neither been started as root nor root has granted another user root privileges. As an unprivileged process, the UNIX Agent can operate only as the Agent start user. For that reason, file transfers, jobs, or file access can only be performed as the Agent start user.

What configuration is required to run a UNIX Agent in the unprivileged mode?

Since the Agent cannot perform any user context switches, the Agent must also be operated in anonymous mode. To turn on the anonymous mode, set the login_check parameter to no in the configuration (INI) file. Also, set the ANONYMOUS_FT/ANONYMOUS_JOB/ANONYMOUS_FE parameters as desired in the UC_HOSTCHAR_* variable that is associated with the Agent. For more information, see UC_HOSTCHAR_DEFAULT - Host Characteristics.

Important! No matter in which mode you run a UNIX Agent, you can configure the permissions to the Agent-specific subdirectories in the Agent INI file, see Agent Unix.

Agent Variables and Folder Permissions

During or after the Agent installation, you must configure a number of Agent-specific variables that control the access to the following folders:

  • backup

    Agent-specific folder that is created when the Agent starts. It is meant for the file-based rollback and it is available for Jobs and File Transfers. You define its path and the corresponding permissions in the UC_EX_PATH_BACKUP Agent variable.

    To use the file-based rollback, you need the OS user under which the related jobs and file transfers are started, and write access to the backup directory

  • temp

    Agent-specific folder that is created when the Agent starts. It is where the Agent stores generated jobs on a temporary basis. You define its path and the corresponding permissions in the UC_EX_PATH_TEMP Agent variable.

  • resources

    Agent-specific folder that is created when the Agent starts. It is where Client-wide resources are stored You define its path and the corresponding permissions in the UC_EX_PATH_CACHE Agent variable.

By default, the access to these folders is NOT restricted and they can be modified by any user. You configure specific permissions for each folder in the [MISC] section of the Agent INI file.

Example 

[MISC]
...
; specified user name or id (id use then used as uid and gid) who becomes the owner of the folder
; default is the user who executes the agent
FolderOwner=osgrp
;FolderOwner_backup=
;FolderOwner_cache=
;FolderOwner_temp=
; specified permission masks are set
; default is any access for everyone for newly created folders
; existing folder permissions are not modified
FolderPermissionMask=rwxrwxrwx
;FolderPermissionMask_backup=
;FolderPermissionMask_cache=
;FolderPermissionMask_temp=
...

For more information, see:

Important! For security reasons, if a login has been specified in the PREP_PROCESS script function, the event file is created in the HOME directory of the user. If no login is specified, the system assumes that the succeeding event job runs with Agent privileges. Therefore, PREP_PROCESS creates the file name with the temp path of the Agent. For more information, see PREP_PROCESS.

At the time when PREP_PROCESS is being processed, the system does not know whether the job will use a login or not. From a technical perspective, this cannot currently be determined, because the event job could also specify the login dynamically (with a :PUT_ATT script statement, see :PUT_ATT).

There are two possible solutions:

  1. Specify a login in PREP_PROCESS (recommended and secure solution).
  2. Assign read and write access to the temp directory of the Agent to the user who is defined in the Event job.

Authorizations for jobreport files are specified using the ReportMode= parameter of the INI file of the UNIX Agent. For more information, see Agent Unix.

Setting Job Execution Limits for Users

You can use the pam_limit.so library to set job execution limits for users. To do so, make sure that the pam_limit.so library is available in your system, otherwise the Agent cannot set the limits correctly.

Note: You only require the pam_limit.so library, you do not need to install and configure PAM.

The Agent binds the library dynamically. If the library is not provided or if the system cannot find it, the Job execution runs without errors but the Agent cannot apply job executions limits for the users. In that case, the system writes the following message into the Agent log: "U02003081 - PAM module 'pam_limits.so' was not found, limits for new process will be not set properly.".

The system searches for the pam_limit.so library in the LD_LIBRARY_PATH environment variable and in the following directories:

  • /lib/security

  • /lib64/security

  • /lib/x86_64-linux-gnu/security

  • /usr/lib/x86_64-linux-gnu/security

When the library is available, the Agent sets the limits for all new processes by default. You can change this behavior using the use_limits parameter in the [PAM] section of the Agent's INI file.

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Important! Make sure you are familiar with the TLS/SSL and certificate implementation before installing and/or upgrading the respective component. For more information, see:

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

Note: The TLS/SSL implementation does not apply to the HP-UX Agent, as it is no longer supported in this version.

The Agent searches for certificates in the most common TLS/SSL stores. If you do not use a default location, the UNIX agents additionally require you to define the SSLCertDir= and SSLCertFile= parameters to load the certificates from the TLS/SSL store.

Default SSLCertDir

  • /etc/ssl/certs

    Platforms: Debian/Ubuntu

  • /etc/pki/tls/certs

    Platforms: Fedora/RHEL/CentOS

  • /usr/local/share/certs

    Platforms: FreeBSD

  • /etc/openssl/certs

    Platforms: NetBSD

  • /var/ssl/certs

    Platforms: AIX

  • /etc/certs/CA directory

    Platforms: Solaris

Default SSLCertFile

  • /etc/ssl/certs/ca-certificates.crt

    Platforms: Debian/Ubuntu

  • /etc/pki/tls/certs/ca-bundle.crt

    Platforms: Fedora/RHEL 6/CentOS

  • /etc/ssl/ca-bundle.pem

    Platforms: OpenSUSE

  • /etc/pki/tls/cacert.pem

    Platforms: OpenELEC

  • /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

    Platforms: CentOS/RHEL 7

  • /etc/ssl/cert.pem

    Platforms: Alpine Linux

  • /etc/certs/ca-certificates.crt

    Platforms: Solaris

If the Agent does not find any certificates or the paths do not exist in your system, then the Agent is not able to connect to the Automation Engine.

You can use different commands to search for the certificates in your system. Only a privileged user, such as root, can search in these folders.

Examples - SSL_CERT_DIR

sudo find /etc/ssl/ -name '*DigiCert*'

sudo find /etc/ -name 'DigiCert_Global_Root_CA.pem'

Examples - SSL_CERT_FILE

sudo grep -R "DigiCert" /etc/ssl/

sudo grep -R "DigiCert Global Root CA" /etc/

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

Installing the Agent

Follow the steps below to install the agent.

  1. Transfer the TAR files to the host and set up the system environment.

    On the host, carry out the following steps:

    1. Register with the AE user ID.

    2. Transfer the TAR file ucxj???.tar.gz .

    3. Unpack the TAR files

      gzip -d ucxj???.tar.gz or gunzip ucxj???.tar.gz

      tar -xvf ucxj???.tar

      (Linux: tar -zxvf ucs???.tar.gz)

      The unpacked files are displayed. Make sure you note any TAR messages and verify that all files are unpacked correctly. Once unpacked, you can delete the TAR file .

      Also, make sure that AE is the owner for all files and that the group entry corresponds with the code AE. Only a privileged user, such as root, can make these modifications.

      chown AE * changes the owners of all files to AE.

      chgrp Group_name * changes the user groups of all files.

    4. For actual operation, you can give the program ucxj??? the permissions of a privileged user such as root.

      chown root ucxj??? changes owner to root

      chmod 4755 ucxj??? Sets S-Bit (Set-Userid)

    5. Customize the INI file of the UNIX Agent using an editor such as vi. You can also edit and transfer the INI file on the Admin computer through FTP. The program ucxj??? and the INI file must be in the same directory (see Agent Unix).

      TLS and Certificates

      1. When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

        If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

        If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

        For more information, see Securing Connections to the AE (TLS/SSL).

      2. If you do not want to use the default locations, UNIX agents additionally require you to define the SSLCertDir= and SSLCertFile= parameters in the [AUTHORIZATION] section of the INI file (see Agent Unix) to load the certificates from the SSL store. The files can be stored either in one file per certificate or all certificates in one .pem file.

        • SSLCerDir= location of the trusted CA certificates with each certificate in a separate file, for example,/etc/ssl/certs/

        • SSLCertFile= location of the .pem file with all the trusted CA certificates, for example, /etc/pki/tls/certs/ca-bundle.crt

        The Agent reads the INI file and uses the locations defined there. If they are not defined, the Agent cannot connect and logs it accordingly.

        You can use different commands to search for the certificates in your system. Only a privileged user, such as root, can search in these folders.

        Examples - SSL_CERT_DIR

        sudo find /etc/ssl/ -name '*DigiCert*'

        sudo find /etc/ -name 'DigiCert_Global_Root_CA.pem'

        Examples - SSL_CERT_FILE

        sudo grep -R "DigiCert" /etc/ssl/

        sudo grep -R "DigiCert Global Root CA" /etc/

      Restrict Agent Capabilities

      In the [AUTHORIZATION] section of the INI file ( see Agent Unix), you can use the following parameters to restrict the Agent capabilities in the target system:

      • ft_source= the Agent can be the source of a FileTransfer

      • ft_target= the Agent can be the target of a FileTransfer

      • Execute= the Agent can execute jobs

      • CAU_enabled= the Agent can be updated using CAU

      By default, the Agent is allowed to perform all these functions.

      Permissions

      Once the Agent is installed, a number of subdirectories are created automatically upon starting the Agent. These folders do not have any restrictions. You can restrict the access to these folders in the Agent INI file. For more information, see Agent Variables and Folder Permissions.

      Fork/Batch

      You can start jobs either with the fork function or the batch command. Use the start_type= parameter in the INI file of the Agent to define the value. Depending on the definition, the following rules apply to the Agent:

      • fork: When the Agent is started with a user ID with root rights, jobs can start under any user ID. Otherwise, jobs must run under the user ID used to start the Agent. The Agent uses execle for spawning the job with minimal environment settings in contrast to su - where the complete user environment is loaded.

      • batch: The Agent must start with a user ID with root rights. To prevent an unexpected or unreliable behavior, su - should not be used because the complete shell environment is loaded.

    On the Admin or server computer, adjust the HEADER.UNIX, TRAILER.UNIX and RESTART.UNIX if necessary. For more information, see Executing Jobs.

  2. Optionally, on the host, configure the PAM (Pluggable Authentication Modules) authentication. This authentication is supported for the UNIX platform Agents Solaris, Linux and AIX.

    • PAM library installation

      The PAM library must be installed on your system (depends on the platform you use).

    • PAM library configuration

      The configuration process depends on the UNIX platform that you use. Typically, you handle it using the files /etc/pam.d or /etc/pam.conf. The name of the service complies with the name of the executable Agent file (ucxj???).

    • Agent configuration

      In the INI file of the Agent, set the authentication= parameter in the [MISC] section to pam. Use the parameter libname= in the [PAM] section to specify the path and the file name of the PAM library :

      [MISC]
authentication=pam
[PAM]
libname=/usr/lib/libpam.so

  3. Start the Agent. To do so, make sure that the AE is running, see Multi-Server Operations.

    There are different options to start the Agent:

    • (Recommended) In the background from the $HOME/bin directory (./ucxjlx6)

      Note: If you start the Agent for testing in the dialog, quitting with the DEL key is only possible as of version 1.20 and if the corresponding parameter has been defined in the INI file. Do not set this parameter, but quit from another terminal using the kill -TERM instead.

      If the $HOME/bin directory is set in the system environment PATH, enter the following command:

      nohup ucxj???1> ucxj???.log 2>&1 &

      If the $HOME/bin directory has not been set in the system environment PATH, enter the following commands:

      nohup ./ucxj???1> ucxj???.log 2>&1 &

      You can also use other commands, for example:

      • pid to note displayed process ID

      • ps -ppid for information about the process (not always available)

      • ps -ef | grep ucx for information about all UCX processes

      • ps -e for information about all processes

    • As a java application using the following command:

      java -jar ucxjoss.jar

      The system searches first in the JAVA_HOME environment variable and, if not set, it searches for the java executable in the JAVA_PATH environment variable.

      Optionally, you can also pass other parameters (for example, -Xverbose or -Xloggc) directly to the Java VM for additional tuning or for diagnostic purposes.

    • Using the ServiceManager. You can use ./ucxjlx6 or java -jar ucxjoss.jar from the command line to start the Agent and pass different parameters:

      • -svc%port%: When specified, the ServiceManager displays the connection status along with the Agent name.

      • -i<ini-file>: starts the Agent with a specific INI file

        Example Service Manager

        ucxjlx6 -svc%port% -Ic:\Agent\Agent-Unix.ini

        Note: The -svc parameter should be omitted when starting directly via the command line.

      • -v: Prints the version of the Agent in the output

        Example CLI

        java -jar ucxjoss.jar -v

    Regardless of the option you use to start the Agent, an Agent object is automatically created in Client 0 and stored in the folder HOST. You can configure access permissions to those folders, see Agent Variables and Folder Permissions.

    In AWI, client 0, verify that the Agent is logged on to the Automation Engine.

    Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.

    Assign the new Agent to clients with the required rights using the Agent object definition. For more information, see Authorizations Page.

Shutting Down the Agent

You can use the ServiceManager not only to start but also to end the Agent as a service, see ServiceManager.

Alternatively, you can shut down the Agent using one of the following options:

  • End the Agent normally: kill -TERM pid.

  • In AWI: In the Agents section of the Administration perspective, right-click the relevant and select Stop.

  • Cancel the Agent in emergency cases (network connections are not properly closed): kill -KILL pid or kill -9 pid.

See also: