Universal Agent for Linux Installation
Installation Process
Installation of Universal Agent for Linux is a three-step process:
Step 1 | Download product distribution file (see Universal Agent for UNIX - Distribution File). |
---|---|
Step 2 | Extract the installation files from the distribution file. |
Step 3 | Install the extracted files. |
Extracting the Universal Agent for Linux Installation Files
Stonebranch, Inc. provides separate product distribution files for the following Linux systems:
- x86_64-based systems
- IBM S/390 and zSeries systems
- Debian-based systems
- PowerPC-based systems
Universal Agent for Linux product distribution files are in a compressed tar format.
x86_64-Based Systems
(The RPM package for x86_64-based systems contains the x86_64 qualifier.)
To uncompress and extract the installation files from the product distribution file, issue the following command:
zcat sb-7.7.x.x-linux-3.10-x86_64.tar.Z | tar xvf -
This command assumes that the name of the distribution file is sb-7.7.x.x-linux-3.10-x86_64.tar.Z.
Distribution File
The following table identifies the files contained in the distribution file.
File | Description |
---|---|
Readme.unv | Summary of the installation procedure. |
unv-7.7.x.x-linux-3.10-x86_64.rpm | Linux RPM file format package. |
unv-opscli-7.7.x.x-linux-3.10-x86_64.rpm | Universal Controller Command Line Interface (CLI) RPM file format package. |
Installation script. | |
upimerge.sh | Script that uses the Universal Installation Merge (UIM) module. |
usrmode.inc | User-mode installer main script. |
unvfiles.tar | User-mode installer modules archive; a set of scripts loaded and executed by usrmode.inc. |
unv-python3.11.tar | Python 3.11 Distribution for Universal Agent. |
Note
If your Universal Agent for Linux (x86_64-based systems) distribution file does not contain these files, contact Stonebranch, Inc. Customer Support to obtain a correct distribution file.
IBM S/390 and zSeries Systems
(The RPM package for IBM S/390 and zArchitecture systems contains the s390x qualifier.)
To uncompress and extract the installation files from the product distribution file, issue the following command:
zcat sb-7.7.x.x-linux-3.10-s390x.tar.Z | tar xvf -
This command assumes that the name of the distribution file is sb-7.7.x.x-linux-3.10-s390x.tar.Z
.
Distribution File
The following table identifies the files contained in the distribution file.
File | Description |
---|---|
Readme.unv | Summary the installation procedure. |
unv-7.7.x.x-linux-3.10-s390x.rpm | Linux RPM file format package. |
unv-opscli-7.7.x.x-linux-3.10-s390x.rpm | Universal Controller Command Line Interface (CLI) RPM file format package. |
Installation script. | |
upimerge.sh | Script that uses the Universal Installation Merge (UIM) module. |
usrmode.inc | User-mode installer main script. |
unvfiles.tar | User-mode installer modules archive; a set of scripts loaded and executed by usrmode.inc. |
unv-python3.11.tar | Python 3.11 Distribution for Universal Agent. |
Note
If your Universal Agent for Linux (IBM S/390 and zSeries systems) distribution file does not contain these files, contact Stonebranch, Inc. Customer Support to obtain a correct distribution file.
Debian-Based Systems
To uncompress and extract the installation files from the product distribution file, issue the following command:
zcat sb-7.7.x.x-linux-3-x86_64-deb.tar.Z | tar xvf -
This command assumes that the name of the distribution file is sb-7.7.x.x-linux-3-x86_64-deb.tar.Z
.
Distribution File
The following table identifies the files contained in the distribution file.
File | Description |
---|---|
Readme.unv | Summary the installation procedure. |
unv-7.7.x.x-linux-3-x86_64-deb | Linux RPM file format package. |
unv-opscli-7.7.x.x-linux-3-x86_64.deb | Universal Controller Command Line Interface (CLI) RPM file format package. |
Installation script. | |
upimerge.sh | Script that uses the Universal Installation Merge (UIM) module. |
usrmode.inc | User-mode installer main script. |
unvfiles.tar | User-mode installer modules archive; a set of scripts loaded and executed by usrmode.inc. |
unv-python3.11.tar | Python 3.11 Distribution for Universal Agent. |
Note
If your Universal Agent for Linux (Debian-based systems) distribution file does not contain these files, contact Stonebranch, Inc. Customer Support to obtain a correct distribution file.
PowerPC-Based Systems
(The RPM package for PowerPC-Based systems contains the ppc64 qualifier. A further qualifier, le, identifies it as Little Endian).
To uncompress and extract the installation files from the product distribution file, issue the following command:
zcat sb-7.7.x.x-linux-3.10-ppc64le.tar.Z | tar xvf -
This command assumes that the name of the distribution file is sb-7.7.x.x-linux-3.10-ppc64le.tar.Z
.
Distribution File
The following table identifies the files contained in the distribution file.
File | Description |
---|---|
Readme.unv | Summary the installation procedure. |
unv-7.7.x.x-linux-3.10-ppc64le.rpm | Linux RPM file format package. |
unv-opscli-7.7.x.x-linux-3.10-ppc64le.rpm | Universal Controller Command Line Interface (CLI) RPM file format package. |
Installation script. | |
upimerge.sh | Script that uses the Universal Installation Merge (UIM) module. |
usrmode.inc | User-mode installer main script. |
unvfiles.tar | User-mode installer modules archive; a set of scripts loaded and executed by usrmode.inc. |
unv-python3.11.tar | Python 3.11 Distribution for Universal Agent. |
Note
If your Universal Agent for Linux (PowerPC-based systems) distribution file does not contain these files, contact Stonebranch, Inc. Customer Support to obtain a correct distribution file.
Installing Universal Agent for Linux
Universal Agent for Linux is installed with the unvinst script, which executes the rpm command. The command to start the script must be executed with the superuser ID.
Note
Stonebranch, Inc. strongly recommends the use of the unvinst script for the Linux installation above any other method.
Component Selection
The Universal Agent package contains many components, which are grouped into five categories. Components in some categories are installed and activated optionally, as specified in the unvinst
script by using unvinst
command line parameters.
The following table describes each category, provides the default installation configuration for the components in that category, and identifies the command line parameters to use for components that are optionally installed and activated.
Note
The default installation configuration refers to new installs only. For upgrades, installed component configurations are not changed by the upgrade process.
Category | Default Configuration | Description |
---|---|---|
Base components | Always installed. | Base components are always installed and activated. They include the Universal Broker, Universal Command (UCM), Universal Data Mover (UDM), and others. Base components provide the core agent infrastructure and workload services. |
Universal Automation Center Agent (UAG) | Always installed, but inactive. | Universal Controller utilizes UAG agents to provided distributed, workload automation services. |
Universal Message Service (OMS) | Always installed, but inactive. | OMS is message-oriented middleware that should be deployed on a small set of centrally located servers. It should not be activated on every Agent install. OMS is the network provider for UAG and the Universal Controller. |
Universal Controller command line programs | Not installed. | Universal Controller command line programs provide a command line interface to the Universal Controller. The installation of Universal Controller command line programs is optional. The command line programs are only required on Agents that need to interface with the Universal Controller via the command line. |
Third-party components | Not installed. | This category includes components not developed or maintained by Stonebranch, Inc. |
Starting the Installation Script
To start the installation script, unvinst, issue the following command:
sh ./unvinst [--user username [--userdir directory] [--create_user {yes|no}] ] [--group group name [--create_group {yes|no}] ]
[--keystore {yes|no}] [--security {appdef|default|inherit|pam|pam_sessions}]
[--convert_opsagent [--opsdir directory] ] [--oms_servers network address] [--oms_port port] [--ac_agent_clusters clusters]
[--ac_agent_ip IP address] [--oms_autostart {yes|no}] [--ac_netname ID] [--uag_autostart yes]
[--ac_extension_accept_list list] [--ac_extension_python_list list] [--ac_extension_deploy_on_registration {yes|no}]
[--ac_extension_cancel_timeout value {s|m|h|d}] [--ac_process_cancel_timeout value {s|m|h|d}] [--ac_message_level level]
[--ac_loglvl level] [--opscli {yes|no}] [--usermode_install {yes|no} [--unvdir directory] [--unvcfgdir directory]
[--unvdatadir directory] [--unvport port] [--python {yes|no}] ] [--use_tls1_3 {yes|no}] [--register_ubrokerd {yes|no}] [--ubrokerd_id value]
See Linux Installation Script Parameters and Installation Script Example, below, for a description of the optional parameters that you can issue with unvinst and an example of unvinst with these parameters.
Note
If you want to install multiple Agents on the same machine, or add one or more additional Agents to a machine with a previously installed Agent, some of these installation parameters are required (see Installing Multiple Agents on a Single Machine).
This is a silent install. The output from unvinst is written to file install.log in the current directory. The Agent is installed into directory /opt.
The Universal Broker daemon will be installed and run as the username and groupname specified with the installation script parameters, below.
Note
For this release of Linux RPM, the previous non-RPM version will not be uninstalled. The Administrator can remove the remaining files/directories as needed.
Linux Installation Script Parameters
The following table describes the optional parameters that are available in the UNIX install script (unvinst
) when installing Universal Agent.
The parameters are grouped into the following categories:
Category | Description |
---|---|
Used for base install. | |
Used for an active OMS configuration. | |
Used for an active UAG configuration. | |
Used for Universal Controller CLI programs install. | |
Used for user mode installation. | |
Used to manage third-party components. |
Parameter | Description | Default |
---|---|---|
Base Parameters | ||
-u | Normal UNIX username that is used to execute the Universal Broker daemon. The install grants this user account ownership of all installed files, with the exception of the Universal Agent server components (for example: ucmsrv, udmsrv, and uemsrv) which, due to security requirements, are owned by root and will have their "set user ID on execution" bit set.
| ubroker |
‑create_user | Specification (yes or no) for whether or not to create the user name that will own the installed files as a local user. | yes |
‑userdir | Home directory for the created user account specified by --user.
|
|
-g | Normal UNIX groupname; the Universal Broker daemon will run as this specified group. All installed files will be assigned to this group.
| ubroker |
‑create_group | Specification (yes or no) for whether or not to create the group that will own the installed files as a local group. | yes |
‑keystore | Specification (yes or no) for whether or not to create encryption keys during installation and set up the local Universal Broker as a keystore owner. | no |
-security | Sets the value (default, inherit, pam, pam_sessions, or trusted) of the following configuration options for Universal Agent server components:
The appdef value for -security controls how product configuration options are set; it does not map to a product configuration option. Note pam_sessions is a valid value only for the UCMD Server and UDM Server. | (none) |
-ubroker_start --ubroker_start | Specifies (yes or no) whether or not Universal Broker is started by the Installer when installation is completed. If --ubroker_start is not included in the script, Universal Broker will be started when installation is complete. Note --ubroker_start is ignored for user mode installs. | yes |
‑use_tls1_3 ‑‑use_tls1_3 | If specified (using yes), all components will be set up to use TLS 1.3 by setting the max_ssl_protocol option to tls1_3 (and encrypt to yes for UCMD and UDM). | no |
-register_ubrokerd | Specifies whether the Universal Broker daemon will be defined to systemd for automatic ubrokerd startup. When this value is 'yes' for system mode installs, a systemd unit file named ubrokerd.service is created. For user mode installs, the name of the file is formatted as described by the -ubrokerd_id command line option. The install will attempt to install this file into the configured systemd system unit file directory. If a configured value cannot be determined, the script uses /usr/lib/systemd/system . If this option is not specified, it defaults to 'no', and the ubrokerd daemon is not registered with systemd. | no |
UAG Parameters | ||
-c | Causes
| |
-d | If --convert_opsagent is specified: Identifies the primary install directory for Universal Agent.
|
|
‑oms_servers | Specifies a value, in the format Note You should always include --oms_servers in | (none) |
‑ac_agent_clusters | Specifies the Universal Controller-defined clusters to which this agent will belong. | (none) |
‑ac_agent_ip | Specifies the IP address or host name (which resolves to an IP address) that the Agent reports to the Controller. | (none) |
‑ac_netname | Specifies the network ID that Universal Agent will use. | (none) |
-ac_extension_accept_list | Specifies a comma-separated list of one or more Universal Extensions that the agent will accept via auto-deployment from the Controller.
The value specified for this parameter sets the EXTENSION_ACCEPT_LIST configuration option value. | * |
-ac_extension_python_list --ac_extension_python_list | Specifies a comma-separated list of zero or more Python locations. Each item in the list is expected to contain a complete path to a Python executable. The value specified for this parameter sets the EXTENSION_PYTHON_LIST configuration option value. | /usr/bin/python3,/usr/bin/python,/usr/libexec/platform-python |
-ac_extension_deploy_on_registration --ac_extension_deploy_on_registration | Controls Extension deployment behavior from the Universal Controller.
The value specified for this parameter sets the EXTENSION_DEPLOY_ON_REGISTRATION configuration option value. | no |
-ac_extension_cancel_timeout | Set the EXTENSION_CANCEL_TIMEOUT UAG configuration option, which specifies the length of time a Universal Extension task is given to complete its response to a CANCEL request. If the task fails to finish its own termination processing within the specified timeout period, UAG Server will forcefully terminate the task. The specified timeout must be numeric, but a one-letter suffix is accepted to specify (s)econds, (m)inutes, (h)ours, or (d)ays. If no time unit is specified, the default is seconds. The following maximums are enforced:
Minute, hour, and day maximums are set to ensure that their value represented as a number of seconds does not exceed 2147483647. | 10 |
-ac_process_cancel_timeout | Set the PROCESS_CANCEL_TIMEOUT UAG configuration option, which specifies the length of time an OS task is given to complete its response to a CANCEL request. If the task fails to finish its own termination processing within the specified timeout period, UAG Server will forcefully terminate the task. The specified timeout must be numeric, but a one-letter suffix is accepted to specify (s)econds, (m)inutes, (h)ours, or (d)ays. If no time unit is specified, the default is seconds. The following maximums are enforced:
Minute, hour, and day maximums are set to ensure that their value represented as a number of seconds does not exceed 2147483647. | 10 |
‑ac_enable_ssl | This option is deprecated starting with Universal Agent 7.1.0.0. UAG Server will always attempt to use SSL/TLS for OMS connections. | n/a |
-ac_message_level | Specifies a message level for UAG. The install uses this value to set the MESSAGE_LEVEL UAG configuration option. | (none) |
-ac_loglvl | Specifies a log level for UAG. The install uses this value to set the LOGLVL UAG configuration option. | (none) |
‑uag_autostart | Specifies (yes or no) whether or not the Universal Automation Center Agent (UAG) Server starts automatically when the Universal Broker is started. | yes |
OMS Parameters | ||
‑oms_port | Specifies the port to use to listen for OMS connection requests. | (none) |
‑oms_autostart | Specifies (yes or no) whether or not OMS is started automatically by Universal Broker when Universal Broker starts. | no |
CLI Parameters | ||
‑opscli | Specifies (yes or no) whether or not the Universal Controller Command Line Interface (CLI) tools will be installed. | no |
User Mode Parameters | ||
-U | Specifies (yes or no) for a user mode installation, which defines both of the following:
| no |
-unvdir | If --usermode_install is set to yes: Specifies the Agent binaries (installation) directory. | (none) |
‑unvcfgdir | If --usermode_install is set to yes: Specifies the Agent configuration files directory. |
|
‑unvdatadir | If --usermode_install is set to yes: Specifies the Agent data files directory. |
|
‑unvport | If --usermode_install is set to yes: Specifies the Universal Broker port. | (none) |
-ubrokerd_id --ubrokerd_id | If --usermode_install is set to yes: Specifies the value used to uniquely identify the ubrokerd unit file when the Universal Brokerd daemon is registered with systemd, as directed by the -register_ubrokerd option. This value is used to format a systemd unit file name in the format ubrokerd@<id>.service, where '<id>' is the value specified for this option. If this option is omitted, the value specified for the -unvport option is used. For system mode installs, the unit file name will always be ubrokerd.service. | Value of --unvport option. |
Third-Party Parameters | ||
‑python | Specifies (yes or no) whether the Python 3.11 Distribution for Universal Agent is installed. | no |
Additional Parameter | ||
-? | Displays command line help. | n/a |
Installation Script Example
The following example illustrates Universal Agent for Linux installed with the installation script, unvinst, and optional parameters.
sh ./unvinst --user user1 --userdir /homedir/user --group usergroup --keystore no --convert_opsagent --opsdir /homedir/ops --oms_servers 7878@oms2 --oms_port 7878 --oms_autostart yes --ac_agent_clusters GA Cluster,CA Cluster --ac_agent_ip 127.0.0.1 --ac_netname OPSAUTOCONF --opscli yes --uag_autostart yes --usermode_install yes --unvdir /opt/universal --unvcfgdir /etc/universal --unvdatadir /var/opt/universal --unvport 7887
User Mode Installation
A user mode installation, implemented through use of the usermode_install installation parameter, lets you install multiple Agents on a single machine and change the default installation directories for any Agent being installed.
You must perform a user mode installation for installing an Agent on a machine where one or more Agents already have been installed.
However, you also can perform a user mode installation for the initial installation of an Agent on a machine.
Note
Any user that wants to execute Agent Managers (for example, ucmd, udm, or uem) or Utilities (for example, uctl or uquery) must source the SB_ConfigSetup.env
file within their user profile. This file is installed in the ./etc
directory located under the install directory, and sets environment variables that point to configuration files and to the Broker's .bif
and .plf
files.
Note
You can execute the install as a non-root user if you want to execute the Agent in an unprivileged user mode environment.
Note
Unprivileged users will be given an option to change ownership and permissions of some product files. This message will show after running the installation script:
The installer has created the script to change ownership and permissions of some product files.
Please run the /<unvdir>/unvperms-3156.sh script with root privileges to finish the installation.
Installing Multiple Agents on a Single Machine
If you want to install multiple Agents on the same machine, you must set the following installation parameter values for each Agent being installed in addition to the initially installed Agent.
Note
You also can set these parameters values for the initial installation of an Agent on a machine.
Installation Parameter | Value |
---|---|
yes | |
A username that is different than the username specified for any other Agent installation on this machine. | |
An Agent binaries (installation) directory that is different than the installation directory specified for any other Agent installation on this machine. | |
A Universal Broker port that is different than the port specified for any other Agent installation on this machine. |
Changing the Default Installation Directories
By default, an Agent is installed and configured in default directories.
If you want to change these default directories, or if you want to install multiple Agents on the same machine, you must set the --usermode_install parameter to yes and specify new values in the following parameters. These directories must be different for each Agent on the same machine.
Note
You also can change these directories for the initial installation of an Agent on a machine.
Installation Parameter | Default Directory | Files Installed |
---|---|---|
/opt/universal | Agent binaries | |
/etc/universal | Agent configuration files | |
/var/opt/universal | Agent data files |
Listing Universal Agent for Linux Information
RPM Commands
Information on installed packages is listed with the rpm command. The command must be executed with the superuser ID.
To list information for the Universal Agent for Linux, issue the following command:
rpm -qi unv rpm -qi unv-opscli
Debian Commands
Information on installed packages is listed with the dpkg command. The command must be executed with superuser authority.
To list information for the Universal Agent for Linux, issue the following commands:
sudo dpkg -l unv sudo dpkg -l unv-opscli
Removing Universal Agent for Linux
System Install Removal
Step 1 | Stop the ubrokerd daemon. |
---|---|
Step 2 | Make a backup copy of the |
Step 3 | RPM Commands rpm -e unv-opscli rpm -e unv rm -rf /etc/universal rm -rf /var/opt/universal sudo dpkg -r unv-opscli sudo dpkg -r unv rm -rf /etc/universal rm -rf /var/opt/universal |
Step 4 | Delete the Agent user account ( userdel -r ubroker |
Step 5 | Delete the Agent group ( groupdel ubroker |
User Mode Install Removal
Step 1 | Stop the Usermode Broker. |
---|---|
Step 2 | Make a backup copy of the |
Step 3 | Using the superuser ID, remove all Universal Agent for Linux packages by issuing the following commands: rm -rf <---unvdir> rm -rf <--unvcfgdir> rm -rf <--unvdatadir> |
Step 4 | Delete the Agent user account ( userdel -r [Usermode Broker user] |
Step 5 | Delete the Agent group ( groupdel [Usermode Broker group] |
Agent
To remove an Agent executing in an unprivileged user mode environment (see User Mode Installation), simply stop the ubrokerd
daemon and remove the ./universal
installation directory. To make sure that you do not mistakenly remove a system install directory, attempt the removal with a non-privileged user account or the Broker account.
Linux PAM Customization
Linux installations utilize Pluggable Authentication Modules (PAM) for user authentication. Many of the Universal Agent servers, such as Universal Command (UCMD), Universal Data Mover (UDM), and Universal Control (UCTL), must authenticate user accounts and passwords. Proper PAM configuration is essential for product operation.
There are many organizations and companies that package and distribute the Linux operating system. Most have consistent PAM implementations, but there are exceptions.
All supported Linux installations - except for SUSE 9 and below - require the sample PAM configuration file delivered with Universal Agent to be copied to directory /etc/pam.d:
cp /opt/universal/ucmdsrv/samp/ucmd.pam /etc/pam.d/ucmd
PAM Configuration File
All Universal Agent components utilize the same PAM configuration file.
64-Bit Linux Systems
For 64-bit Linux systems (x86_64-Based systems; S/390 and z/Series systems) its contents are:
auth | required | /lib64/security/pam_pwdb.so shadow nullok |
auth | required | /lib64/security/pam_nologin.so |
account | required | /lib64/security/pam_pwdb.so |
Your Administrator must modify this sample PAM file to meet your local configuration.
Examples of Customized PAM Configuration Files
Universal Agent for Redhat systems 5.0 and greater
auth | include | system-auth |
auth | required | |
account | include | system-auth |
Universal Agent for SUSE-based systems 10.0 and greater
auth | required | pam_unix2.so nullok |
auth | required | |
account | include | common-account |
Alternative Universal Agent for SUSE 10.1
auth | required | pam_unix2.so nullok |
auth | required | |
account | include | common-account |
Configuring the Agent to Run a Task without a Password
Prior to release 5.1, Universal Automation Center used the ops_suexec.nopass file, which listed all trusted users.
As of release 5.1, this file no longer is used. To apply your desired security configuration, access the UAG SECURITY configuration option in the uags.conf
configuration file:
- If you do not want security, set the value to inherit.
- If you want security, set the value to pam and update the following files:
- Check the /etc/pam.d/ucmd configuration file to ensure that it contains the minimum PAM security settings (see Examples of Customized PAM Configuration Files, above).
- Add the following to /etc/universal/uacl.conf for each user: uag_work_request [username],allow,noauth
Also, verify that the user has a /home directory defined.