Editing Installing the Cartographer GUI

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

==Overview==

The Cartographer GUI is a completely native Java application (not Applet) that does not require any additional libraries nor Jar files other than what comes with the standard Sun distribution.  It does not require any Java Native Interface (JNI) access to system nor third-party libraries.  It communicates with Cartographer agents using the [[XMP]] protocol and can discover and display the dependencies between systems and applications.  '''Finally, the Cartographer GUI is not a manager in the traditional sense in that it neither stores data nor polls agents -- it is a tool to view the dependency relationships between systems and applications in a distributed system.'''

==Java Requirements==

The Cartographer GUI application is written in native Java and Swing and currently uses only bundled libraries that ship with the Sun distribution.  Testing has not been done with non-Sun Java installations.  At the time of this writing, the version of Java used is listed below.  Newer versions of Sun Java are expected to work with no issues.

<pre>
%java -version
java version "1.6.0_01"
Java(TM) SE Runtime Environment (build 1.6.0_01-b06)
Java HotSpot(TM) Server VM (build 1.6.0_01-b06, mixed mode)
</pre>

Development and testing of the Cartographer GUI occurs primarily on Linux and Solaris.  Testing is occasionally performed on Windows.

== Unpacking/Installing the Distribution (Zip Format) ==

The Cartographer GUI is distributed as a zip file containing all the necessary jars.  Upon downloading, unzip the contents into the desired directory.

On UNIX:
<pre>
%unzip Cartographer.zip
Archive:  Cartographer.zip
  inflating: Cartographer.jar        
  inflating: Xmp.jar                 
  inflating: jgraph.jar              
  inflating: jgraphlayout.jar  
</pre>

On Windows, simply right-click on the zip file and extract to the desired directory.

The jar files contained in the distribution are:

* '''Cartographer.jar''' contains the Java code for the Cartographer GUI 
* '''Xmp.jar'''  contains the Java code to communicate, via the [[XMP]], with Cartographer agents.  All protocol code is encapsulated in this jar file.
* '''jgraph.jar'''  contains the basic JGraph classes for Swing-like open-source graph component for Java.  See [http://www.jgraph.com JGraph] for more information.
* '''jgraphlayout.jar''' contains the JGraph layout code for automatic positioning of graphs.  See [http://www.jgraph.com JGraph] for more information.

==Installing (Linux RPM) ==

To install the Cartographer GUI RPM on Linux, issue the following command.

<pre>
rpm -iUv cartographer-gui-0.33-1.noarch.rpm
</pre>

The resulting files are placed in ''/opt/cartographer-gui''.

==Installing (Windows Installer) ==

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 Cartographer GUI Installer|this page]] to see the sequence of screens.

==Starting Cartographer GUI==

'''UNIX:'''

Start the Cartographer GUI by first changing to the directory that it is installed in.

<pre>
% java -jar Cartographer.jar
</pre>

'''Windows:'''

You can start the Cartographer GUI by following the UNIX instructions above or by double-clicking on the ''Cartographer.jar'' file.

'''After Starting'''

After starting, you will see the initial window:

[[Image:Cartographer-initial.gif|center|400px|Cartographer Main Window]]

Check and modify any options via the dialog shown below.  In particular, make sure that the ''authenUser'' parameter is set to that which you configured Cartographer agents to communicate with.  The ''authenUser'' parameter can be thought of similar to an SNMP community string in that it is used to identify a set of allowable protocol operations and access permissions.  However, unlike SNMP, XMP communication provides for privacy and authentication via its use of SSL. 

[[Image:Cartographer-options.gif|center|300px|Cartographer Options Dialog]]

==Discovering a System==

Discover a system by launching the Discover dialog.

[[Image:Cartographer-discover.gif|center|300px|Cartographer Discover Dialog]]

Once the system is identified, via domain name or IP address, Cartographer GUI establishes a session with the Cartographer agent residing on that system.  Its dependencies, peers, and system information is queried.  If the discover operation was initiated with depth greater than zero, the discover thread will attempt to do a depth-first-search (DFS) of the dependency graph between the target system and others.  The discover operation will proceed up to the specified depth.

==Visualizing Dependency Relationships==

Once systems, applications, and dependencies are discovered, you can visualize or ''view'' them using one of the many different view options available.

[[Image:Dependency-view.gif|center|400px|Dependency View]]

The image above shows a dependency view of the Krupczak.org enterprise network.  The nodes are positioned using a custom-developed concentric-circles layout algorithm developed specifically for Cartographer GUI.  Nodes positioned closer to the center have a greater degree.  The degree of a vertex (computer system) is the number of edges incident to it.  Edges represent dependencies both to and from other systems.

==Querying a System==

The Cartographer GUI also allows you to query systems via the XMP protocol.  To do so, first make sure the proper authenUser parameter is set.  Then, via the Dependency View, right-click on a node that supports XMP (light blue), and a pop-up menu will appear.  The query menu, for an example system, is shown below.

[[Image:Xmp-query-menu.gif|center|300px|Pop-up Query Menu]]

The image below depicts the results of a performance query against an example system.

[[Image:Xmp-query-result-1.gif|center|200px|Performance Query Results]]

The image below depicts the results of a CPU table query against a test system.

[[Image:Xmp-query-result-2.gif|center|250px|CPU Table Query Results]]

Finally, the image below depicts an Endpoint query against a Windows development system.  The Endpoint table can be queried to find out which processes are communicating over the network and to which systems/ports.

[[Image:Xmp-query-result-3.gif|center|350px|Endpoint Table Query Results]]

==Platform Notes==

Some Linux distributions come pre-installed with the GNU Java interpreter.  While the Cartographer GUI code ''may'' work with the GNU Java interpreter, it is not tested nor officially supported.

==See Also==

* [[Cartographer Project Release Notes]]
* [[Cartographer FAQ|FAQ]]
* [[Warranty]]
* Krupczak.org [[License agreement]]
* [[Cartographer]]
* [[XMP]]
* [[Distributions|Software Distributions]]
* [http://www.jgraph.com JGraph]