Page tree
Skip to end of metadata
Go to start of metadata

Overview

The AIE Agent provides communications between the project control tools (AIE-CLI) and the applications and services that make up the AIE project. The Agent must be running on all host machines in your deployment before you can start any other processes.  

The Agent can be started manually if desired, or it can run automatically as a Windows service or Linux daemon. The latter option is more convenient for multi-node systems. 

An overview of the AIE project ecosystem, including the AIE Agent, is presented in Developing in AIE - Concepts and Tools.

If the AIE Agent has crashed or has been stopped for any reason, check for AIE-related processes that are still running. These must be manually killed before you can restart the AIE node.

 

View incoming links.

Start the AIE Agent

The Agent may already be running.

The AIE Agent is installed as a Windows service or Linux daemon by default during AIE Installation.  It that case it is probably already running and there will be no need to start it. 

In a clustered production system it would be usual to run the AIE Agent as a service or daemon (see below on this page), but in early development on an unclustered system it may be more convenient to run the Agent in a command window. This makes it easier to stop the Agent temporarily so you can delete the files in the data-agent directory while making iterative adjustments in the project's representation.

To start the Agent, do the following:

Open a command prompt, and run <install-dir>\bin\aie-agent.exe. The default port is 16999.

WINDOWS:<install-dir>\bin\aie-agent.exe -p 16999 -d c:\data-agent
LINUX:  [root@localhost bin]# sh aie-agent -p 16999 -d /opt/attivio/data-agent

This table lists all available startup options for the AIE Agent: 

OptionDefault ValueDescription
-p16999The port the AIE Agent uses (it cannot conflict with ports used by AIE processes). Defaults to port 16999 if no port is specified.
-d./data-agent

The Agent's data directory.  The agent log file and process specific data appears here, including the project index files.

Note that the default location for the index is within the AIE install tree. This is convenient for early experimentation, but it might not be the best place to store these files in a production system. Consider locating the files in a place where they won't be endangered by a reinstall or upgrade.

For additional information about the Agent, see More About Agents.

Running the Agent Without A Shell

There are a few reasons why you may want to run the agent on the host non-interactively, that is, without a shell. For example:

  • On multi-user operating systems, you want the agent to continue running beyond the interactive session of a single user.
  • You want the agent to start up automatically upon system startup or reboot.

You can achieve these modes of execution through  Windows Services and Unix Daemons .

Running the Agent as a Windows Service

There are two ways of setting the agent to run as a Windows Service:

  • using the installer at install time (recommended)
  • manually at some point after the install  

The sections below detail how to do either.

Installer Method

The AIE installer on Windows provides the option of installing the agent as a Windows Service.  At that time, you can also configure which port and data directory the agent uses.

You can verify the installation of the service by opening the Services dashboard in Control Panel's Administrative Tools and look for the aie-agent-service entry.  It is configured to automatically start, so that it automatically starts on system boot. You can further verify that the Agent is running by going to http://<AGENT_HOST>:<AGENT_PORT>/admin to view a simple agent console listing the agent's data directory, running processes, and dead processes.

Manual Method

Using the installer is the recommended way to install the agent as a service on Windows.  However, you can set up the agent as a Windows Service at some point in time after the install of AIE by using the executable aie-agent-service.exe, located in <install-dir>\bin on Windows.

Running the AIE Agent as a Windows service requires AIE Installation with Windows Administration privileges, and subsequent log in as Administrator.

  1. Open a command prompt using Administrator privileges.
  2. Change directory to <install-dir>\bin

  3. Execute the install command

    install the service
    <install-dir>\bin>aie-agent-service.exe /install
    
  4. To configure the agent's parameters, use the Windows Registry Key editor to edit HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\aie-agent-service.  Modify ImagePath to have the desired startup arguments, like "<install-dir>\bin\aie-agent-service.exe -p 16999 -d <install-dir>\<agent_data_dir>"
  5. The same instructions apply to start a service upon first install as in "The Installer Method."
  6. The same instructions apply to verify a running service as in "The Installer Method."

Uninstalling the Service

To uninstall the service, do the following:

  1. Stop the service using by right clicking and selecting Stop in the Services dashboard in the Control Panel's Administrative Tools.
  2. Open a command prompt using Administrator privileges:
  3. Change directory to $ATTIVIO_HOME%\bin

    command prompt
    C:\>cd installed_software\attivio\aie_4.0.6\bin
    C:\installed_software\attivio\aie_4.0.6\bin>
  4. Execute the uninstall command:

    uninstall the service
    C:\installed_software\attivio\aie_4.0.6\bin>.\aie-agent-service.exe /uninstall
    Service is already stopped.
    Uninstalled service 'aie-agent-service'.
    C:\installed_software\attivio\aie_4.0.6\bin>
  5. Check the status (optional)

    check status
    C:\installed_software\attivio\aie_4.0.6\bin>.\aie-agent-service.exe /status
    Could not get status.
    C:\installed_software\attivio\aie_4.0.6\bin>

Running the Agent as a Linux Daemon

Setup

On Unix/Linux, the agent as a daemon is not setup via the installer so that you can run the installer as a non-privileged user.  To setup the agent to run as a Linux Daemon follow these steps using a privileged user or effective privileges elevated via a prefix command such as sudo:

  1. Execute the AIE Agent Daemon install script.  Be prepared to provide values for ATTIVIO_HOME, the agent's port, the agent's data directory, and the Linux user to run as.  Some values are suggested as defaults and you may type <ENTER> to accept the suggested values.

    $ sudo /opt/attivio/bin/install-aie-agent-daemon.sh
    Welcome to the AIE Agent Daemon Install Script!
    
    Confirmed that this script is running with superuser privileges.
    
        **** OS distribution is Red Hat (or CentOS) ****
    
    Populating variables...
    Enter Attivio Home: /opt/attivio
    Enter AIE Agent's port - an integer between 1 and 65535, inclusive: 16999
    Enter AIE Agent's data directory (fully qualified path): /opt/attivio/agent_data
    Enter the user to run the AIE Agent as: aieadmin
    
    Completing writing daemon script...
    Registering daemon with system...
    Daemon 'aie-agent-daemon' successfully registered with the system.
    $ 
  2. Start the agent daemon for the first time.  Note that you need not do this if you reboot.  In that case, AIE starts the daemon automatically.

    $ sudo /etc/init.d/aie-agent-daemon start
    $
  3. Verify the agent is running.

    $ sudo /etc/init.d/aie-agent-daemon status
    The AIE Agent is running
    $

    You can further verify that the Agent is running by going to http://<AGENT_HOST>:<AGENT_PORT>/admin to view a simple agent console listing the agent's data directory, running processes, and dead processes.

    The agent now runs as daemon under the user you specified, even after you logout of the current shell and terminal.  Furthermore, the agent automatically starts on system boot/reboot.

Uninstall

On Linux, the agent as a daemon is not uninstalled via the uninstaller so that you can run the uninstaller as a non-privileged user.  To uninstall the agent as a Linux Daemon follow these steps using a privileged user or effective privileges elevated via a prefix command such as sudo:

  1. Stop the agent daemon.

    $ sudo /etc/init.d/aie-agent-daemon stop
    Attempting to Kill AIE Agent
    $
  2. Confirm AIE Agent is not running.

    $ sudo /etc/init.d/aie-agent-daemon status
    The AIE Agent is stopped
    $
  3. Execute the AIE Agent Daemon uninstall script.  A confirmation message appears when it has successfully uninstalled the daemon.

    $ sudo ./uninstall-aie-agent-daemon.sh
    
    Welcome to the AIE Agent Daemon Uninstall Script!
    
    Confirmed that this script is running with superuser privileges.
    
        **** OS distribution is Red Hat (or CentOS) ****
    
    Un-registering daemon with system...
    
    Daemon 'aie-agent-daemon' successfully un-registered with the system.
    $

 

More About Agents

Agent Console

The agent provides a simple web console that shows basic information about the started processes.  You can access this console at: http://host:16999/admin. The console shows:

  • All processes started by the agent, whether they are still running or not. 
  • The time when the process started.
  • The process' native PID.
  • When the process finished initializing
  • The process' admin console link (if available). 
  • Only processes started on the agent's host.

Agent Data Storage

AIE Index Files

For an unclustered (single-node) project, the data-agent directory tree contains the project's index files.  

The agent's data directory shows detailed data about each process started by the agent. It also contains data files (and the index files) for each project loaded and run by the Agent.

The <data-agent> directory may appear in various locations:

  • If you are running AIE Agent as a service, the <data-agent> directory will appear as a sibling of the <install-dir>, as in:

    c:\attivio\
    c:\data-agent\
  • If you started AIE Agent from the command line, the default <data-agent> directory is a child of the current directory. So if you start aie-agent.exe in <install-dir>\bin, where the executable resides, look for the data in <install-dir>\bin\data-agent\.
  • There is a data-directory option to aie-agent.exe (-d), so you can write the <data-agent> directory anywhere you like.

The <data-agent> directory contains the aie-agent.log file and two subtrees:

  • procinfo - This area maintains log and output files for AIE processes such as nodes and configservers. This data is organized by handle id (a monotonic number).  You can find the process id in the status display of the CLI.  Each process directory contains:
    • The command executed to run that process.
    • The standard error and output files.
    • The working directory of the process.
  • projects - Working files for each AIE project will be found on this branch. For instance, the AIE Index files (for single-node projects) are located in the <data-agent>\projects\<project-name>\<environment>\data\data-local\index\index\ directory.

Logs and Data

If the data and log directories for processes are not set in the project's topology configuration, they default to corresponding directories in the Agent's data directory, as described in the Agent Data section above. NOTE that each process' handle directory changes upon restart, therefore this is not an ideal configuration for any project outside of a simple local development/testing environment.

There are several situations where the Agent may not be able to access/create the appropriate log and data directories for each AIE process:

  • When the Agent doesn't have write access to the specified path(s).
  • When the path doesn't work on the target OS or is invalid (e.g. a Unix style path on Windows server, this can happen when the nodes are running on mixed OSes). By default, the topology element in topology-nodes.xml specifies the attribtue projectdir="." which is determined by the client (aie-cli) which starts the project. 
  • By default each node's log and data directories are located under that data-agent directory but in a mixed OS deployment, the data-agent path may be incompatible. For example, in Windows:

    C:\attivio\<version>

    in Linux, it would be:

    /opt/attivio/<version>

    In this case, you must specify valid log and data directories for all nodes running on Windows hosts.
  • When the data and/or log directories simply aren't defined anywhere (not at the node/nodeset level and without attivio.project defined).
  • No labels