The Comprehensive Guide to Notification Server Agent for UNIX/Linux/Mac Installation and Configuration 

The most frequent issue with the Notification Server Agent for UNIX deals with installation. This document is designed to be a definitive guide to installing the Notification Server Agent for UNIX (agent). Included are descriptions of the various installation and configuration methods and supporting information.

Overview

There are five installation methods and five configuration methods for the Notification Server Agent for UNIX. They are:

Installation methods

1. Push from the Notification Server Console.
2. Pull from a browser on the client computer.
3. Manual using the aex-bootstrap file.
4. Manual using the aex-nsclt package.
5. Manual using the uuencoded aex-bootstrap (not covered in this document).

Configuration methods

1. Automatic or default
2. Notification Server Console Agent Settings
3. .aex-agent-install-config.xml
4. aex-configure
5. UNIX environment variables

The following table shows which configuration methods are or can be used with each installation method:

* A push installation will download and use a copy of the .aex-agent-install-config.xml file to the client receiving the agent. If no updates were made to the agent settings in the Notification Server Console, then the file will contain default settings.

** A pull installation will download a copy of the .aex-agent-install-config.xml file with default settings. It is possible for a user to modify these settings prior to manually running agent installation (for good or ill).

*** aex-configure can be run at any time after the agent installation to change certain agent settings, including Notification Server hostname. It does not modify an existing installation path even though there is a prompt for that path.

Altiris Console Screens

The agent installation screen can be found in the Notification Server Altiris Console. Navigate to the Configuration tab, expand the left-pane menu to Altiris Agent > Altiris Agent Rollout, and click on Altiris Agent Installation. Note that this screen can have from one to three tabs, depending on the solutions installed – one each for Windows, UNIX, and Macintosh. Be sure to select the appropriate tab for the desired client computer platform you will be working with—in this case, UNIX.

Computers

Following is a sample from a 6.0 Console with the "Install Altiris UNIX Agent" screen selected:

Agent Package Locations and Files

The UNIX agent package files are installed to the Notification Server’s NSCap directory. There is a separate package for each of the supported platforms. Based on a default installation of the Notification Server, the agent packages are found in the following location on the Notification Server: C:\Program Files\Altiris\Notification Server\NSCap\bin\UNIX\Agent

For example, the following folders in 8.5 RU4 exist for supported operating systems:

• AIX\PowerPC
• HP-UX\IA-64
• HP-UX\PA-RISC
• Linux\x64
• Linux\x86
• Linux-Debian\x64
• Linux-Debian\x86
• Mac\x86
• Solaris\Sparc
• Solaris\x86

* Note that Itanium servers can run PA-RISC software.

Agent Package File Description

 

The packages for the various platform contain an identical set of files. The files consist of:

aex-boostrap: A compressed, platform-specific file used to set up the environment on the client, download and run the aex-nsclt installation package and configure the agent installation.

aex-bootstrap (UUencoded): A compressed, platform-specific, uuencoded version of the bootstrap used when normal connection, download, and installation methods fail.

aex-nsclt: A compressed, platform-specific package used to actually install the agent on a client computer.

agent-upgrade: Shell script used by the upgrade policy. Recommended for any installation where a previous build of the agent is already installed. It is designed to recognize and correctly handle any previous installation.

Agent Package File Contents

 

Following is a complete list of the package contents for each platform. Note that the package format and compression method are platform-specific.

AIX: aex-bootstrap.Z
aex-bootstrap.Z.uu
aex-nsclt.6.2.1378.bff.Z
agent-upgrade

HP-UX: aex-bootstrap.Z
aex-bootstrap.Z.uu
aex-nsclt.6.2.1378.depot.Z
agent-upgrade

Linux:aex-bootstrap.gz
aex-bootstrap.gz.uu
aex-nsclt-6.2-1378.i386.rpm
agent-upgrade

Solaris (Sparc):aex-bootstrap.Z
aex-bootstrap.Z.uu
aex-nsclt-6.2.1378-sol-sparc.Z
agent-upgrade

Solaris(x86):aex-bootstrap.Z
aex-bootstrap.Z.uu
aex-nsclt-6.2.1378-sol-intel.Z
agent-upgrade

Configuration

Configuration is required to direct the agent on the client to the correct Notification Server, among other things. Depending on the installation method chosen, the installation directories, run-levels and logging details can also be configured.

Automatic Method

A normal push installation will use default settings for the installation of the agent on a client computer. The agent will be configured to communicate with the Notification Server doing the push installation. In this case, only the Connection and Authentication information need be specified. No Agent settings need be modified.

Note: The push installation will create a .aex-agent-install-config.xml file that contains default settings and download it to the client computer for use during the installation process. This method is labeled ‘automatic’ since no user interaction is required for this process.

Agent Settings Method

The Agent Settings screen can be accessed from the "Install Altiris UNIX Agent" screen by entering adding a computer, highlighting it, and selecting ‘Install Settings…”. A new window will open. Click on the Agent Settings tab. Any of the settings on this screen can be modified and will affect the ‘push’ installation of the agent to the selected client computer.

Any changes made here will also be used when saving the .aex-agent-install-config.xml file from the Install XML tab.

.aex-agent-install-config.xml Method

The "Install Settings" window can be used to create a .aex-agent-install-config.xml (config.xml) file. This is most helpful during a manual installation process.

An installation using aex-bootstrap or aex-nsclt will search for an .aex-agent-install-config.xml file in the following locations in this order. The search ends when the first occurrence is located:

1. If the current directory is not root, check the current directory
2. If the current directory is not root, check the parent directory
3. Check in the folder specified by the AGENT_INSTALL_DIR environmental variable.
4. Check in the folder specified by the AEXCLIENT_CONFIG_XML_DIR environmental variable.
5. Check in folders: /tmp, /var, and /opt/altiris

Note that this search does not use the clients $PATH environment variable for additional locations.

It has to be noted that the native package manager may change the current working folder when installing the Altiris UNIX Agent package (aex-nsclt). For this reason, aex-configure (Altiris UNIX Agent configuration tool) may be executed from a different place and thus may not be able to find the configuration XML file. This behavior is typical, for example, in case of the GNU/Linux platform and the RPM package manager. Therefore, we recommend the /tmp or /var directories when using aex-nsclt.

Sample .aex-agent-install-config.xml

<?xml version="1.0" encoding="utf-16"?>
<NSAgentConfiguration>
<NSName>'<SMPServername>'</NSName>
<NSProtocol>http</NSProtocol>
<Settings UseNSIPAddress="no" NSIPAddress="<192.0.2.1>" UseDomain="no" EnableNICError="no" Upgrade="yes" Start="yes" AllowNonRoot="yes" RunLevel="rc2;rc3;rc5">
<CurlSSL SSLVerifyPeer="no" SSLVerifyHost="no" CAInfo="" CAPath="" />
<EventLog LogDir="%INSTDIR%/var" LogFile="aex-client.log" LogSize="256" LogLevel="Error" SysLogLevel="None" />
<ComputerInformation Name="<Hostname>" Domain="empty" />
<InstallDir>/opt/altiris/notification/nsagent</InstallDir>
<BinDir>/usr/local/bin</BinDir>
<TempDir>/tmp</TempDir>
<GuidDir>%INSTDIR%/etc</GuidDir>
<GuidFile>host.GUID</GuidFile>
<EventQueueDir>%INSTDIR%/var/queue</EventQueueDir>
<TasksDir>%INSTDIR%/var/tasks</TasksDir>
<PackagesDir>%INSTDIR%/var/packages</PackagesDir>
<SWDDir>%INSTDIR%/var/swd</SWDDir>
</Settings>
<ClientDetails>
<SerialNumber>null</SerialNumber>
<AssetTag>null</AssetTag>
<EmployeeID>null</EmployeeID>
<ContactName>none</ContactName>
<ContactPhone>none</ContactPhone>
<ContactEmail>none</ContactEmail>
<Location>none</Location>
<Department>none</Department>
<Description>none</Description>
</ClientDetails>
</NSAgentConfiguration>

aex-configure Method

This utility can be run after a manual installation of the agent. By default, it is found in:              

/opt/altiris /notification/nsagent/bin/aex-configure

It can be run with default settings without prompts or it can be run in interactive mode. aex-configure has the following command-line options:

• --help, -hDisplay this usage information and exit immediately.
• -cleanRemove aex-configure created files prior to uninstall.
• -configureAutomatically configure/upgrade an installation from an XML config file.
• -iconfigure Interactively configure/reconfigure an installation ignoring any XML file.
• help <-command> Display help on the specified command

Note: The following will discuss the ‘-configure’ and ‘-iconfigure’ commands.

-configure

This option automatically configures or upgrades an installation using an XML config file. This option has the following sub-options:

• -noimode (optional): By default, if this option fails to find either a previously installed agent or an XML-formatted configuration file, it steps into the interactive mode.By specifying this option, the interactive fallback mode is disabled.
• -nosearch (optional): Do not search for the installed agent.
• -dir <Agent-Base-Dir> (optional): Altiris Agent for UNIX and Linux installation root folder.
• -quiet (optional): Generate no output.

Running ‘aex-configure –configure’ on an existing installation without an update .aex-agent-install-config.xml file or without update environment variables will cause the program to set all configurable items to their current state. Essentially, it makes no changes.

-iconfigure

Interactively configure/reconfigure an installation ignoring any XML file. The options are

• -nosearch (optional): Do not search for the installed agent.
• -dir <Agent-Base-Dir> (optional): Altiris Agent for UNIX and Linux installation root folder.
• -quiet (optional): Generate no output.

./rcscript stop

Stopping Altiris Agent for UNIX and Linux:[OK]

# ./aex-configure -iconfigure

Altiris Agent for UNIX and Linux Configuration utility.
Using interactive configuration, cancel with Ctrl-C.

Please answer the following questions.
Defaults are in brackets. To accept a default just press enter.
Name or IP of Notification Server? If your server uses HTTPS or a non-default port, it is necessary to specify the full URL.
Example: https://www.altiris.com:8083 :
The directory the Agent package has been installed to? (/opt/altiris/notification/nsagent):
Do you want to keep the old settings? (yes):
Allow program execution by unprivileged users? (yes):
Which Run levels should the agent be installed in? (rc2;rc3;rc5;):
In which directory should the Agent's log file be stored? (/opt/altiris/notification/nsagent/var):
What should the name of the Agent's log file be? (aex-client.log):
What should be the maximum size, in kilobytes, of the Agent's log file? (256):
What level of logging should be used for the Agent's log file (error,warning,info,debug,dbgverbose,devnote)? (error):
What level of logging should be used for the system log file (none,error,warning,info)? (None):
Directory to use, which should be in the PATH, to create links to the Agent's binaries? (/usr/bin):
Temporary directory for the Agent's use? (/tmp):
Agent's event queue directory (default recommended)? (/opt/altiris/notification/nsagent/var/queue):
Agent's tasks directory (default recommended)? (/opt/altiris/notification/nsagent/var/tasks):
Do you want the Agent started after configuration? (yes):
Removing aex-* links in /usr/bin
Removing RC init links and scripts

Migrating Agent 6.2.1378 settings...

Creating customized RC and environment scripts.
Setting up RC scripts to start Agent at system start.

Starting Altiris Agent for UNIX and Linux.
Altiris Agent for UNIX and Linux is running
Configuration complete.

Note: The prompt shows the server name as an http url. It is acceptable to enter only the <Hostname> (short or FQDN), e.g., example.com / Altiris.com

Note: The log file size is the total size of all log files combined – not each individual log file. The number of log files to be created can be configured in the /opt/altiris/notification/nsagent/etc/client.conf file.

Note: By default, links to certain agent commands are created in the /usr/bin directory. This path can be changed. Allowing ‘program execution by unprivileged users’ will allow any non-admin user to run these commands. Commands include: aex-sendbasicinv, aex-refreshpolicies, etc. A non-privileged user can run aex-swdapm to view the list of applicable tasks but cannot actually run the task. Only an admin/super-user can run tasks.

Environment variables Method

The following environment variables can be set on a unix or linux client prior to running aex-bootstrap, aex-configure or the aex-nsclt package. These settings will be used to perform basic configuration of the agent.

Aex-nsclt Package installation:

AGENT_INSTALL_DIR – default directory is /opt/Altiris/notification/nsagent

Aex-configure:

AEXCLIENT_CONFIG_FILE – location of .aex-agent-install-config.xml file. Use this one.
AEX_INSTALL_NSNAME – Hostname of NS Server to communicate with
AEX_INSTALL_AUTOSTART – Setup rcscripts to start agent process for specified run levels
AEX_INSTALL_RUNLEVELS – Run levels on which the agent process should start

Installation

Prerequisites

1. Ensure that name resolution is setup, either via DNS or by adding the Notification Server's hostname and IP address to the client's /etc/hosts file. There is an option to use the Notification Server's IP address but this is not recommended as it requires reconfiguration of the Notification Server's codebase and snapshot settings.
2. Ensure that SSH or telnet is enabled on the client. SSH is preferred, of course. This is a requirement for only the Push installation method from the NS Console.
3. The push install must be able to detect the shell actually in use (Bourne vs. C). No loading one type while changing the environment to indicate another type.
4. Customized prompts (long, colored or multi-lined) on the client may cause a push install to fail.
5. Login scripts may not have interactive prompts if doing a push install.
6. Computers do not need to be discovered (via Network Discovery Solution) prior to doing a push install to them.
7. Third-party firewalls must be configured to allow an SSH connection from the NS/SMP to the ULM client using the credentials provided in the ‘Installation Settings” screen when doing a push from the NS/SMP Console.

Push from the NS Console

A Push installation is initiated in the Notification Server Console. The agent installation screen can be found in the Notification Server Altiris Console. Navigate to the Configuration tab, expand the left-pane menu to Altiris Agent, Altiris Agent Rollout and click on ‘Altiris Agent Installation’. Note that this screen can have from one to three tabs, depending on the solutions installed—one each for Windows, UNIX and Macintosh. Be sure to select the appropriate tab for the desired client computer platform you will be working with.

The push installation will attempt to connect to a specified client computer and download a bootstrap file that will setup the client environment, download and run the aex-nsclt package.

The basic steps for a Push installation are

1. Required: Ensure that name resolution is setup, either via dns are by adding the Notification Server's hostname and IP address to the client's /etc/hosts file. There is an option to use the Notification Server's IP address but this requires reconfiguration of the Notification Server's codebase and snapshot settings and affects Windows, Unix and all other clients reporting to the reconfigured NS server. 
2. Required: Ensure that SSH or telnet is enabled on the client. SSH is preferred, of course.
3. On the Install Altiris UNIX Agent tab, add the IP address or hostname of the client.
4. Highlight the client's entry on the main window and click the Install Settings button.
5. Add the root password. As of the 6.x release, the user must be root.
6. Save the settings and close the window.
7. Ensure that the computer is still highlighted.
8. Click the Install Altiris Agent button. A new window should appear showing the status of the push install.
9. When it states that the bootstrap has started, that's the last message you will get. The agent should shortly be found in the /opt/Altiris/notification/nsagent directory on the client. It should report basic inventory and shortly appear in the 'all platforms' collection, as well as other appropriate collections. If the push fails for any reason, it will be indicated in this window. You can view the installation logs for clues as to why and correct them.

Pull from a browser on the client computer

1. On the Notification Server Console's Configuration tab, expand Altiris Agent, Altiris Agent Rollout, and select Altiris Agent Installation. Then, click the Install Altiris UNIX Agent tab.
2. Toward the bottom of the page, there is a section titled URL of download page for UNIX users.
3. In that section, select the appropriate platform and allow the page to refresh. The URL in the next line will update with the appropriate platform ID value.
4. Copy that URL and browse to it from each client computer. (It may be possible to use curl or wget to download the package.)
5. Follow the instructions on the download page to download the aex-bootstrap file, the .aex-agent-install-config.xml file, set permissions and run the aex-bootstrap file.

The URL listed on the above page can be distributed via email or other method to all applicable recipients. Be sure that the URL contains the appropriate platform ID value as there is a separate package for each platform.

Manual using the aex-bootstrap file

1. Required: Ensure that name resolution is setup, either via dns are by adding the Notification Server's hostname and IP address to the client's /etc/hosts file.
   
   Note: the aex-agent-install-config.xml file is optional. If not found by the bootstrap, the default settings will be used. If you do not wish to use the aex-agent-install-config.xml, you may start at step 9 below.
2. On the Configuration tab, expand Altiris Agent, Altiris Agent Rollout, and select Altiris Agent Installation.
3. Click the Install Altiris UNIX Agent tab.
4. Select the appropriate Operating System from the platform drop-down list farther down the right-hand screen. Allow the screen to refresh.
5. Click the Show me this page link. A new window will open.
6. Click .aex-agent-install-config.xml link in the middle of the page.
7. Go through all three tabs. Ensure that the proper values have been selected or modified. It is recommended that you accept the defaults.
8. The last tab has a save button. Save the file to a specific location.
9. Download the aex-bootstrap.gz or aex-bootstrap.Z file, depending on the platform, to the same location as the aex-agent-install-config.xml file.
10. "Gunzip" the aex-bootstrap.gz file or "uncompress" the aex-bootstrap.Z file.
11. Use the command chmod u+x aex-bootstrap to ensure the aex-bootstrap is executable.
12. Set any desired environment variables if not using a config.xml file.
13. Run one of the following commands, depending on environmental requirements. Note that the server name is required to avoid subsequent configuration.
    1. ./aex-bootstrap <ns server hostname>
    2. sudo ./aex-bootstrap <ns server hostname>
14. The agent should soon install to the /opt/Altiris/notification/nsagent directory on the client. It should report basic inventory and appear in the 'all platforms' collection, as well as other appropriate collections, after collection update runs on the Notification Server. At that point, you can enable inventory policies or whatever solution you are working with.

Manual using the aex-nsclt package

This is the most direct method of installing the agent but requires configuration. All other methods have a default configuration.

To install the aex-nsclt package:

1. Copy the platform-specific aex-nsclt file from the Notification Server.
2. Setup appropriate environment variables, if desired.
3. Run the installer for the current platform. For example, on a Linux computer, the command line would be one of the following:
   1. rpm –i aex-nsclt-6.2-1378.i386.rpm
   2. sudo rpm –i aex-nsclt-6.2-1378.i386.rpm
4. If environment variables were not used, configure the agent by either of the following methods:
   1. Copy a .aex-agent-install-config.xml to an appropriate location and run ‘aex-configure –configure’
   2. Run ‘aex-configure –iconfigure’ and answer all prompts. The Notification Server name must be entered. All other values can be defaulted by pressing Enter.

Appendix

Setting up a smbmount in Linux to the NS Server’s NSCap Directory

It may be desirable to setup a mount from a Linux or UNIX computer to easily copy the agent installation files to a local client computer. Following are instructions for doing so in Linux.

1. Create the /mnt/nscap directory.
2. The NSCap directory on the Notification Server should already be a share.
3. Run: smbmount //<ns server name>/nscap /mnt/nscap -o username=<ns server name>\\<user on ns server>.
4. Enter the windows user password when prompted.
5. cd to /mnt/nscap to view nscap files on windows computer.
6. Cd to the appropriate platform directory, e.g., /mnt/nscap/Bin/Unix/Agent/Linux/x86 and copy the appropriate file(s) to the client computer.

Additional aex-bootstrap Options

Usage: aex-bootstrap (NS|URL) (-test) (-dir DIR) (-speedlimit N) (-onefile)

This program will get all files at a URL/NS Package into the specified directory. It can also be used to download a file from a URL. When started with no NS/URL argument configuration must be provided in an XML file present in the same directory, or (in the case of a automatic reschedule) at one of the standard locations.

Arguments:arg 1 = name of NS, URL of a package or file

Optional Commands:

• -test: output version.
• -dir <dir> : specify Agent installation directory.
• -speedlimit <N> : limit download to n KB/sec.
• -onefile: URL is for a single file, download to current directory, no other action.