Editing Cartographer Agent Installation

[[File:Download.png|right|link=Distributions|alt=Download Software|Download Software]]

==Overview==

There is a single Cartographer agent release that encompasses all supported platforms.  That is, the single release contains binaries, libraries, plugins, and configuration files needed to run on all supported platforms.  Files are built using a naming scheme that identifies the platform that they are compiled for.

==Home Directory Location==

The default/suggested locations for Cartographer agent installation are listed below.  However, the software can be installed in virtually any location that is suitable for your distributed system.  It is recommended, though, that the software not be installed on remote filesystems nor network shares.  The software should be installed on a local filesystem.

* UNIX ''/opt/cartographer''
* Win32 ''c:\program files\cartographer''
* Win64 ''c:\program files (x86)\cartographer''

==Unpack/Install the Release==

The software is available in ''tar'',''zip'', Solaris ''pkg'', and Linux ''rpm'' formats.

* '''UNIX tar or zip file'''
<pre>
mkdir /opt/cartographer
cd /opt/cartographer
tar xvof /path-to-release/release.tar
</pre>

<pre>
mkdir /opt/cartographer
cd /opt/cartographer
unzip release.zip
</pre>

* '''Solaris Package'''
<pre>
pkgadd -d ./cartographer.pkg
</pre>

* '''Linux RPM'''
<pre>
rpm -iUv cartographer-1.3-1.i386.prm
</pre>

* '''Windows (zip file)'''

Double-click on the ''zip'' file and extract to ''c:\program files\cartographer''.

* '''Windows (executable installer file)'''

Double-click on the ''exe'' file and the graphical installer will take care of the rest.  Accepting the default options is usually easiest and best.  Go to [[Next Next Next Installer|this page]] to see the sequence of screens.

==File Manifest==

The agent release contains all files for all platforms.  Files that are platform-specific contain a suffix specifying the platform they are compiled for.  The platform-specific suffixes are identified below.  The files included in each release are:

* '''Agent Engine Binaries'''
** xmpd-''platformsuffix''

* '''MIB2 Plugins'''
** mib2-''platformsuffix''

* '''Cartographer Plugins'''
** cartographer-''platformsuffix''

* '''Test Plugins'''
** testplugin-''platformsuffix''

* '''Tools'''
** ntsetup.exe - NT setup utility for configuring agent to run as Windows service
** xmpquery-''platformsuffix'' - XMP query tool
** xmptomrtg-''platformsuffix'' - XMP query tool that outputs data in MRTG format
** restartxmpd.exe - tool used by agent engine to restart itself during automatic upgrades
** restartxmpd.sh - tool used by agent engine to restart itself during automatic upgrades
** init.linux - Linux ''/etc/init.d'' script
** init.solaris - Solaris ''/etc/init.d'' script
** cartographertray.exe -- Windows system tray program
** xmpgetsubgraph-''platformsuffix'' - XMP query tool to retrieve a target agent's sub-graph

* '''Libraries'''
** libssl-''platformsuffix'' - OpenSSL library
** libcrypto-''platformsuffix'' - OpenSSL crypto library
** libxml2.dll - Windows libxml2 library
** ssleay32.dll, libeay32.dll - OpenSSL libs for win32
** zlib1.dll - Windows zlib library for data compression
** pthreadVC1.dll - Windows pthreads library
** iconv.dll - Windows library for character encoding conversions
** libpcre-''platformsuffix'' - Perl Compatible Regular Expressions library

* '''Configuration Files'''
** xmpd.xml - Agent configuration settings
** cartographer.pem - Agent certificate authority keys
** appdata.xml - Cartographer plugin data file storing application data
** connectiondata.xml - Cartographer plugin data file storing connection data
** cartographer.xml - Cartographer plugin configuration settings
** cartographer-local.xml - Local, system-specific Cartographer-plugin configuration directives

==Configuring Automatic Startup==

Instructions below detail how to start the agent automatically at system-boot time.  On Windows, ''ntsetup.exe'' should be run from a ''command.com'' shell.  On Vista, run the ''command.com'' shell as ''administrator''.

If you installed Cartographer via RPM, Windows installer, or Solaris package, this step is not necessary.

* Linux (tar format only; no need to do this step after rpm package installation)
<pre>
cp init.linux /etc/init.d/cartographer
chkconfig --add cartographer
</pre>

* Solaris (tar format only; no need to do this step after pkg installation)
<pre>
cp init.solaris /etc/init.d
ln -s /etc/init.d/cartographer /etc/rc3.d/S91cartographer
</pre>

* Windows (zip file)
<pre>
cd \program files\cartographer
.\ntsetup.exe -v -create
</pre>

* Windows (executable installer file)

Select ''Yes'' when the installer asks if you'd like to create the service entry.

==Configuring the Cartographer Agent==

Inspect the various configuration files to tailor the agent configuration to your environment.  Below are settings that you may wish to change.  Configuration files contain a version number which is used by the agent for distributing upgrades.  Newer configuration files (those with greater version numbers) are automatically distributed to other agents.

See [[Example_Cartographer_Agent_Configuration|this page]] for more information and examples.

* '''xmpd.xml'''

** autoupgrade - default to true for automatic upgrades
** defaultmanager - name or IP address of system to send Traps to by default.  Traps are also sent, by default, to peer systems.
** verbose - default to false; set to true for more verbose logging
** authenuser - used to configure different protocol operation levels and access controls.

* '''connectiondata.xml'''

Add/edit/delete entries that indicate, to the Cartographer plugin, which ports are used for which applications.

* '''appdata.xml'''

Add/edit/delete entries that indicate which processes belong to with applications

* '''cartographer.xml'''

** xmpAuthenUser - name of authenUser parameter that the Cartographer plugin should use when contacting other agents.  This parameter should also be a valid ''authenuser'' configured in ''xmpd.xml''.

** dependencyScanInterval - interval, in seconds, between dependency discovery.  The smaller the interval, the more CPU Cartographer will consume.  The longer the interval, the less granularity Cartographer has for dependency discovery.

* '''cartographer-local.xml'''

** This file is used to provide system-specific directives to the Cartographer plugin and is updated and distributed by Cartographer agents.

==Starting and Stopping the Cartographer Agent (Manually)==

'''To stop Cartographer:'''

UNIX:

<pre>
/etc/init.d/cartographer stop
</pre>

Windows:
<pre>
net stop Cartographer
</pre>

'''To start Cartographer:'''

UNIX:

<pre>
/etc/init.d/cartographer start
</pre>

Windows:
<pre>
net start Cartographer
</pre>

Windows Installer:

If you are using the Windows installer, select ''Yes'' when asked if you would like to start Cartographer now.

==Whats Next?==

You can check to see if the Cartographer agent is running, and correctly configured, by querying it with [[xmpquery]].  A plethora of XMP query files is contained in the Cartographer agent distribution.  They include ''xmpgetstatus.xml'', ''xmpgetcartographer.xml'', ''xmpgetdepends.xml'', and ''xmpgetiftable.xml''.

On Windows, you can also check to see if the Cartographer agent is running and correctly configured via the [[cartographertray|Cartographer system tray]] icon.

==Supported Platforms and Platform Specific Notes==

'''Cartographer agents run on the following platforms:'''

* Solaris 9+ Sparc/64-bit (''-solaris'' platform suffix)
* Solaris 9+ on x86 (''-solx86'' platform suffix)
* Linux systems containing 2.4+ kernels on x86 (''-linux'' platform suffix)
* Windows 2000/XP/2003/Vista/2008 (''-win32'' platform suffix) both 32-bit and 64-bit

'''Notes:'''

* Solaris 11 is not yet supported; porting and testing is underway.
* If you are using iptables or other firewall packages, you will need to open TCP/5270 for use by Cartographer.
* On 64-bit Windows, 32-bit Cartographer runs in 32-bit mode just fine.
* 64-bit Linux kernels are supported just fine. Some required 32-bit libs, however, may not be installed by default.
* A port to MacOS is being contemplated but has not yet been finalized.
* Ports to neither the iPhone/iPod nor Android have been planned at this time.
* On Solaris, Cartographer agents are started with init scripts rather than the service management facility
* The agent release contains its own builds of OpenSSL and PCRE that conform to our platform-specific naming scheme.  Doing so makes installation and deployment, as well as upgrading, simpler and more consistent.  The current version of OpenSSL shipped with Cartographer is 0.9.8g 19 Oct 2007.  The current version of PCRE is 8.01 Jan 2010.
* On UNIX, we use the native XML libraries; on Windows, we distribute a Windows version of libxml2.
* On UNIX, we use the native POSIX threading libraries (pthreads); on Windows, we distribute a Windows version of pthreads.

==See Also==

* [[Warranty]]
* [[License agreement]]
* [[ntsetup]]
* [[Cartographer]]
* [[Cartographer Project Release Notes]]
* [[Next_Next_Next_Installer|Windows Agent Installer]]
* [[XMP]]
* [[xmpd]]
* [[xmpquery]]
* [[xmptomrtg]]
* [[cartographertray]]
* [[Distributions|Software Distributions]]
* [[Installing the Cartographer GUI]]
* [http://www.xmlsoft.org/ Libxml2]
* [http://sources.redhat.com/pthreads-win32/ Pthreads for Win32]
* [http://www.openssl.org OpenSSL]
* [http://www.pcre.org/ PCRE]