Installing the Agent for UNIX

This page guides you through the installation of a UNIX Agent, which can be used for 32-bit and 64-bit. To make use of its full capacity, it is recommended to use the 64-bit Agent.

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.

Watch the Video: Installing UNIX Agents

Notes:

  • 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 "???."

  • Additional installation steps are required before the Agent can be started and used if you intend to use one of the available authentication methods. For more information, see Agent Authentication.

  • For information about CallAPI files and their implementation, see CallAPI for UNIX.

  • 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

This page includes the following:

Overview

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 two 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.

    Example

    • 64-bit host: sudo crle -64 -s <agent bin absolute path> -u

    • 32-bit host: sudo crle -s <agent bin absolute path> -u

What are root privileges needed for?

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 thetasks. 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?

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.

Requirements

  • User ID AE has been created.

  • Privileges for the out (UC_EX_PATH_JOBREPORT) and temp (UC_EX_PATH_TEMP) directory (see List of Agent Variables):

    • Owner: read, write and execute permissions

    • Group: read, write and execute permissions

    • World: read, write and execute permissions

  • If permissions are missing, the Agent changes the permissions for these directories.

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).

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.

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.

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

You can use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.

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

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

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

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

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/

TLS/SSL Agents (in containers or on-premises) and the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer and not the JCP directly. The ingress / HTTPS load balancer must be reachable and requires a certificate for authentication. The address of the load balancer must be defined on both sides: the Automation Engine and the Agent / TLS Gateway.

Important! When you install or upgrade Agents manually for an Automic Automation Kubernetes Edition system, you have to make sure that you configure your Agents and/or TLS Gateway to reach the TCP or HTTPS load balancer and not the CP or JCP directly. Also, make sure that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to the AAKE Cluster.

Important!

  • When you install or upgrade Agents manually for an Automic Automation Kubernetes Edition system, you must configure your Agents and/or TLS Gateway to reach the TCP or HTTPS load balancer and not the CP or JCP directly.

  • Your HTTPS load balancer must have the required certificates in place. For more information, see Connecting to the AAKE Cluster.

Installing the Agent for UNIX

  1. On the host, grant the necessary rights to the user ID AE.

    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.

  2. 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. Note any TAR messages and verify that all files are unpacked correctly. You can delete the TAR file after unpacking it.

        Make sure that all files have the correct owner and group entry. AE must be the owner. The group must correspond 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. 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).

        1. Use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

          For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.

        2. If you do not use self-signed certificates, you have to load them from the TLS/SSL store. To do so, define the SSLCertDir= and SSLCertFile= parameters in the [AUTHORIZATION] section of the INI file of the Agent ( see Agent Unix). The certificates 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/

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

        • Change owner to root

          chown root ucxj???

        • Set S-Bit (Set-Userid)

          chmod 4755 ucxj???

        Note: You need at least the 755 permissions for executables such as Agent, job messenger, and file events.

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

  3. 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/libpam32.o

  4. Start the Agent.

    1. On the server computer, make sure the AE system is running. For more information, see Multi-Server Operations.

    2. On the host, carry our the following steps:

      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.

      1. Start the Agent in the background from the $HOME/bin directory.

        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 &

        Note displayed process ID pid.

        Information about the process with ps -ppid. Not always available.

        Information about all UCX processes with ps -ef | grep ucx.

        Information about all processes with ps -e.

      2. An Agent object is automatically created in system client 0 and stored in the folder HOST.

        The backup directory for the file-based rollback is automatically created when you start the Agent. This directory is available for jobs and file transfers. You can define the path for the backup directory in the Agent variable UC_EX_PATH_BACKUP.For more information, see List of Agent Variables.

        Note: 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.

    3. On the admin or server computer, 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.

  5. On the host, end the Agents using one of the following options:

    • End the Agent normally: kill-TERM pid

    • End the Agent through 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: