Installing the Agent for UNIX

This topic guides you through the installation process 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.

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.

Overview

The agent for UNIX operating systems can be installed to either run as a privileged or an unprivileged process. It is recommended to install it as a privileged process because only in this mode, the agent can operate with full capabilities.

There are two 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 where the start user has to be a member of, 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

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

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, for example.

What configuration is required to run a Unix agent in the unprivileged mode?

As the agent cannot perform any user context switches, the agent must also be operated in anonymous mode. To turn on anonymous mode, set the login_check parameter to no in the configuration file and the settings ANONYMOUS_FT/ANONYMOUS_JOB/ANONYMOUS_FE=Y as desired in the UC_HOSTCHAR_* object 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 PREP_PROCESS, the event file is created in the user's HOME directory. 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.
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.

Installing the Agent for UNIX

1. Grant the necessary rights to user ID "AE" (Host)

   • Jobs can either be started with the function fork, or the batch command. Set the agent's INI file parameter start_type= to the corresponding value. Depending on this setting, the following rules apply for the agent:
   • "fork" - Jobs can start under any user ID if the agent has been started under a user ID with root rights. If no root right has been assigned, jobs must run under the user ID under which the agent has been started. 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 under a User ID with root rights. "su -" should not be used in order to prevent an unexpected or unreliable behavior because the complete shell environment is loaded.

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

   • Host:

     1. Register with user ID AE.
     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. The TAR file can be deleted after unpacking.

        Ensure 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 via FTP. The program ucxj??? and the INI file must be in the same directory. For more information, see Agent Unix.
     5. For actual operation, the program ucxj??? can be given 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 permissions 755 for our executables such as agent, job messenger, and file events.

   • Admin Computer or Server Computer:

     • Adjust the HEADER.UNIX, TRAILER.UNIX and RESTART.UNIX if necessary. For more information, see Executing Jobs.

3. Configure authentication via PAM (optional). (Host)

   Authentication via Pluggable Authentication Modules is supported for the agents of the following UNIX platforms: 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 will handle it by 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???).
   • Configuring the agent
     In the INI file of the Agent Unix, set the authentication= parameter in the [MISC] section to pam. You must specify the path and the file name of the PAM library in the libname= ([PAM] section) section:
     
     [MISC]
     authentication=pam
     
     [PAM]
     libname=/usr/lib/libpam32.o

4. Start the Agent.

   • Server computer:
     • The AE System must be running. For more information, see Multi-Server Operations

   • Host:

     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 when the corresponding parameter in the INI file has been set. Do not set this parameter, but quit from another terminal using the kill -TERM instead.

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

        Enter the following if the directory $HOME/bin has been set in the system environment PATH:
        nohup ucxj??? 1> ucxj???.log 2>&1 &
        Enter the following if the directory $HOME/bin has not been set in the system environment PATH:
        nohup ./ucxj??? 1> ucxj???.log 2>&1 &
        Note displayed process ID pid.
        Information about this 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 0000 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. Note that for using 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.

   • Admin computer or Server computer:

     1. Verify whether the agent is logged on.
     2. Start the AWI for client 0000. Information about agents is available in the Administration perspective. Because a newly logged-on agent has not yet been assigned a client, it can only be viewed in the client 0000. The new agent can now be assigned to clients with the required rights via the Agent object.

5. End the Agent (Host) by using one of the following options.

   • End the agent normally:
     kill-TERM pid
     
   • End the agent via the AWI:
     Select the context-menu command Stop for the relevant agent in the Agents section of the Administration perspective.
   • Cancel the agent in emergency cases. Network connections are not properly closed.
     kill -KILL pid or kill -9 pid

You can use the ServiceManager to start and end the agent as a service. For more information, see ServiceManager.