<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "1.2">
  <!ENTITY manrevision "1.2">
  <!ENTITY date "September 2006">
  <!ENTITY app "lat">
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.GNOME.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Jan 30, 2002
  
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
	 <title>&app; Manual V&manrevision;</title>
	 <copyright> 
		<year>2005</year>
		<holder>MMG Security, Inc.</holder> </copyright>

<!-- translators: uncomment this:

  <copyright>
   <year>2003</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
	 <publisher> 
		<publishername> MMG Security, Inc. </publishername>
	 </publisher>
	 &legal; 
	 <authorgroup> 
		<author> 
		  <firstname>Loren</firstname>
		  <surname>Bandiera</surname> 
		  <affiliation> 
			 <orgname>MMG Security, Inc.</orgname>
		  </affiliation>
		</author>

<!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
       <othercredit role="translator">
	<firstname>Latin</firstname> 
	<surname>Translator 1</surname> 
	<affiliation> 
	  <orgname>Latin Translation Team</orgname> 
	  <address> <email>translator@gnome.org</email> </address> 
	</affiliation>
	<contrib>Latin translation</contrib>
      </othercredit>
-->
	 </authorgroup>

<!-- According to GNU FDL, revision history is mandatory if you are -->
<!-- modifying/reusing someone else's document.  If not, you can omit it. -->
	 <revhistory>
<!-- Remember to remove the &manrevision; entity from the revision entries other
   than the current revision. -->
   		<revision> 
		  <revnumber>&app; Manual V&manrevision;</revnumber>
		  <date>&date;</date> 
		  <revdescription> 
			 <para role="author">Loren Bandiera</para>
			 <para role="publisher">MMG Security, Inc.</para>
		  </revdescription>
		</revision>
	 </revhistory>
	 <releaseinfo> This manual describes version &appversion; of &app;.
		</releaseinfo>
	 <legalnotice> 
		<title>Feedback</title>
		<para>To report a bug or make a suggestion regarding the <application>&app;</application> application or this manual, follow the directions in the <ulink url="ghelp:gnome-feedback" type="help">FIXME</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
	 </legalnotice>
  </articleinfo>
  <indexterm><primary>lat</primary></indexterm>
  <indexterm><primary>text editor</primary></indexterm>

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
  <sect1 id="lat-intro"> 
	 <title>Introduction</title>
	 <para>An LDAP server is a hierarchical database system. It's typically used to provide a 
	central store of information on users and other configuration data.</para>
	 <para><application>&app;</application> allows you to browse LDAP-based directories and
	add/edit/delete entries contained within. It can store profiles for quick access to different
	servers. There are also different views available such as Users, Contacts, Groups and Hosts which 
	allow you to easily manage objects without having to deal with the intricacies of LDAP.</para>
  </sect1>
<!-- ============= Getting Started =========================== -->
  <sect1 id="lat-getting-started"> 
	 <title>Getting Started</title>

<!-- ============= To Start lat ============================ -->
	 <sect2 id="lat-to-start"> 
		<title>To Start &app;</title>
		<para>You can start <application>&app;</application> in the following ways:</para>
		<variablelist>
    		<varlistentry>
    		<term><guimenu>Applications</guimenu> menu</term>
    		<listitem>
    		<para>Choose <menuchoice><guisubmenu>System Tools</guisubmenu><guimenuitem>LDAP Administration Tool</guimenuitem></menuchoice>. </para>
    		</listitem>
    		</varlistentry>
    		<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>Execute the following command: <command>lat</command></para>
    		</listitem>
    		</varlistentry>
    		</variablelist>
	</sect2>
	
	<sect2 id="lat-when-you-start">
	
		<title>When You Start &app;</title>	
		<para>When you start <application>&app;</application>, the following window is displayed:</para>
	
		<figure id="lat-window"> 
		  <title>&app; Window</title>
		  <screenshot> 
			 <mediaobject> 
				<imageobject> 
				  <imagedata fileref="figures/lat_window.png" format="PNG"/>
					 </imageobject>
				<textobject> <phrase>Shows lat main window.</phrase>
				</textobject> 
			</mediaobject>
		  </screenshot>
		</figure>
	
		<para>The <application>&app;</application> window contains the following
		  elements: </para>
		<variablelist> 
		  <varlistentry> <term>Menubar</term> 
			 <listitem> 
				<para>The menus on the menubar contain all of the commands you need to work with the LDAP server in <application>&app;</application>.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Toolbar</term> 
			 <listitem> 
				<para> The toolbar contains a subset of the commands that you can access from the menubar.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>View area</term> 
			 <listitem> 
				<para> The view area contains the different views of the data on the LDAP server. </para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Output window</term> 
			 <listitem> 
				<para>The output window displays the information about entries found in the directory. </para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Statusbar</term> 
			 <listitem> 
				<para>The statusbar displays the username that was used to login to the LDAP server</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
		<para>When you right-click in the output window, the application displays a popup menu. The popup menu contains the most common commands. </para>

      <para>
        In <application>&app;</application>, you can perform the same action in different ways. For example, you can import an LDIF file in the following ways:
                  <informaltable frame="all">
                    <tgroup cols="2" colsep="1" rowsep="1">
                      <colspec colname="COLSPEC0" colwidth="50*"/>
                      <colspec colname="COLSPEC1" colwidth="50*"/>
                      <thead>
                        <row valign="top">
                          <entry colname="COLSPEC0">
                            <para>UI Component</para></entry>
                          <entry colname="COLSPEC1" align="left"> 
                            <para>Action</para></entry>
                        </row>
                      </thead>
                      <tbody>
                        <row valign="top">               
                          <entry><para>Window</para></entry>
                          <entry><para>Drag a file into the <application>&app;</application> window from another application such as a file manager.</para></entry>
                        </row>
                        <row valign="top">               
                          <entry><para>Menubar</para></entry>
                          <entry><para>Choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Import LDIF...</guimenuitem></menuchoice>.</para>

</entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </informaltable>
      </para>
   </sect2>
</sect1>

<!-- ================ Usage ================================ -->
  <sect1 id="lat-usage"> 
	 <title>Usage</title>

<!-- ============= To Create a New Entry ======================== -->
	 <sect2 id="lat-server-new-entry"> 
		<title>To Create a New Entry</title>
		<para>To create a new entry, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>New</guimenuitem></menuchoice>. Depending on the current view selected (Computers,Contacts,Groups,Users), the application displays a new entry dialog.</para>
	 </sect2>

<!-- ============= To Delete an Entry ======================== -->
	 <sect2 id="lat-server-delete-entry"> 
		<title>To Delete an Entry</title>
		<para>To delete an entry, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Delete</guimenuitem></menuchoice>. The application will display a confirmation dialog before proceeding.</para>
	 </sect2>

<!-- ============= To Connect to a Server  ======================== -->
	 <sect2 id="lat-server-connect"> 
		<title>To connect a Server</title>
		<para>Choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Connect</guimenuitem></menuchoice> and the connect dialog
		will appear. By default, you only need to specify a hostname. You can specify more options if you wish and also
		save the connection as a profile for future use.</para>
		<para>If you don't save it as a profile then it will only last for the duration of the session. 
		Next time you use <application>&app;</application> it won't be remembered.</para>
	 </sect2>

<!-- ============= To Re-login to a Server  ======================== -->
	 <sect2 id="lat-server-relogin"> 
		<title>To Re-Login to a Server</title>
		<para>At any time you can re-login to the server.  Say for example you logged in with anonymous access and now need to do something which requires privileges.  To re-login, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Re-login...</guimenuitem></menuchoice>. The application will display a dialog to get the new login information.  The status bar will show who you are currently logged in as.</para>
	 </sect2>

<!-- ============= To Disconnect from a Server ======================== -->
	 <sect2 id="lat-server-disconnect"> 
		<title>To Disconnect from a Server</title>
		<para>To disconnect from a server, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Disconnect</guimenuitem></menuchoice>. The application will display a confirmation dialog before proceeding.</para>
	 </sect2>

<!-- ============= To Import Entries from an LDIF file ======================== -->
	 <sect2 id="lat-server-import-ldif"> 
		<title>To Import Entries from an LDIF file</title>
		<para>To import some entries from an LDIF file, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Import LDIF...</guimenuitem></menuchoice>. The application will display a file chooser dialog to select the file.</para>
		<para>You could also just drag and drop the file from your file manager into the
		output window.  This also works with plain text blocks.</para>
	 </sect2>

<!-- ============= To Export an entry to an LDIF file ======================== -->
	 <sect2 id="lat-server-export-ldif"> 
		<title>To Export an entry to an LDIF file</title>
		<para>To export an entry to an LDIF file, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Export LDIF...</guimenuitem></menuchoice>. The application will display a file chooser dialog to select the file to save as.</para>
		<para>You could also right click on the entry and choose <menuchoice>Export</menuchoice>.</para>
	 </sect2>

<!-- ============= To setup your directory for Samba ======================== -->
	 <sect2 id="lat-samba-setup"> 
		<title>To setup your directory for Samba</title>
		<para>To setup your directory for Samba, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Populate for Samba...</guimenuitem></menuchoice>. You need to provide the
following information and then click on the ok button.</para>

		<note>
	              <para>You have the Samba schema installed on your directory in order for this to work.</para>
	        </note>

		<itemizedlist> 
		<listitem><para>Server - The name of the server to populate .</para></listitem>
		<listitem><para>SID - This is the Security Identifier for your domain. You can obtain it by running the command 'net getlocalsid' from a terminal.</para></listitem>
 		<listitem><para>Domain - Name of your Samba domain</para></listitem>
		<listitem><para>Administrator - The user name of the system administrator</para></listitem>
		<listitem><para>Guest - The user name of the system guest user</para></listitem>
		<listitem><para>Users - Where to store user objects</para></listitem>
		<listitem><para>Groups - Where to store group objects</para></listitem>
		<listitem><para>Computers - Where to store computer objects</para></listitem>
		<listitem><para>ID Map - Where to store ID map (only needed if your server is a domain member server)</para></listitem>
		</itemizedlist>
	 </sect2>

	<!-- ================ Mass Edit ================================ -->
	  <sect2 id="lat-mass-edit"> 
		 <title>To make the mass changes to entries</title>

	<!-- ============= Mass Edit ======================== -->
		 <sect3 id="lat-mass-edit-intro"> 
			<title>Mass edit of directory entries</title>
			<para>There are times when it is necessary to make changes to a number of entries. Mass edit can help with this task. 
			Choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Mass Edit...</guimenuitem></menuchoice> to bring up the mass edit dialog.</para>

			<sect4 id="lat-mass-edit-server">
			<title>Server</title>
			<para>This selects the server to perform the mass edit(s) on.</para>
			</sect4>

			<sect4 id="lat-mass-edit-criteria">
			<title>Criteria</title>
			<para>The filter is used to select the entries that will be edited. For example, it could be all users in a certain department.</para>
			</sect4>

			<sect4 id="lat-mass-edit-Edits">
			<title>Edits</title>
			<para>This describes the edits you wish to perform. You can add, replace or delete attributes from the entries.
			You can add and remove the edits as necessary. Once you are happy with them click on the OK button and the program will do the necessary work.</para>
			</sect4>
		 </sect3>

	  </sect2>

<!-- ============= To Quit LAT ======================== -->
	 <sect2 id="lat-server-quit"> 
		<title>To Quit LAT</title>
		<para>To quit LAT, choose <menuchoice><guimenu>Server</guimenu><guimenuitem>Quit</guimenuitem></menuchoice>.</para>
	 </sect2>

  </sect1>

<!-- ============= Preferences =========================== -->
  <sect1 id="lat-preferences"> 
	 <title>Preferences</title>

<!-- ============= To Start lat ============================ -->
	 <sect2 id="lat-pref-browser-selection"> 
		<title>Browser selection</title>
		<para>This controls how the LDAP browser works selects an entry. You can
		choose between a single or double click. The default is to double click.</para>
	</sect2>
	
	 <sect2 id="lat-pref-profiles"> 
		<title>Profiles</title>
		<para>The profiles are used to store connection information about LDAP servers
		that you connect to frequently so you can access them quickly. You can add, edit
		or delete profiles from here.</para>

		<para>The following documents the various profile options available.</para>

		<note>
		<para>At a minimum a profile needs to have a name, host, and port.</para>
	        </note>

		<sect3 id="lat-pref-profiles-name">
		<title>Profile name</title>
		<para>The thing a profile needs is a name. This is used to identify the profile
		and this name will be displayed in the various views.</para>
		</sect3>

		<sect3 id="lat-pref-profiles-basic-setttings">
		<title>Basic Settings</title>
		<para>The basic settings for a profile are the hostname of the LDAP server and
		the TCP port that it listens on.</para>
		</sect3>

		<sect3 id="lat-pref-profiles-advanced-setttings">
		<title>Advanced Settings</title>
		<para>The following advanced settings are available</para>
		<variablelist> 
		  <varlistentry><term>Base DN</term> 
			 <listitem> 
				<para>This specifies the root of the LDAP directory. <application>&app;</application> attempts to query this value when it connects to the server. It is not mandatory</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Username</term> 
			 <listitem> 
				<para>The user to login to the directory with. If no user is specified it's assumed to be an anonymous connection.</para>
				<para>The format of the username should be a valid DN, eg: cn=admin,dc=example,dc=com</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Password</term> 
			 <listitem> 
				<para>The password for the above mentioned username. This value will be stored in the user's GNOME keyring
				unless the 'prompt for password' checkbox is active.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Prompt for password</term> 
			 <listitem> 
				<para>Causes the program to not store password information for this profile. The user will be prompted for a password instead.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Encryption</term> 
			 <listitem> 
				<para>Specified the level of encryption to use for the connection.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Server Type</term> 
			 <listitem> 
				<para>Defines what kind of software the LDAP server is running.</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
		</sect3>

		<sect3 id="lat-pref-profiles-server-views">
		<title>Server Views</title>
		<para>This section allows the user to specify what views are active for this profile. The
		views can be customized as follows:</para>
		<variablelist> 
		  <varlistentry><term>Attributes</term> 
			 <listitem> 
				<para>Defines the column names and what attribute values are displayed in the view.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Default new container</term> 
			 <listitem> 
				<para>This specifies where to create new objects for the view. If nothing is specified the user will be asked to select a location each time.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Filter</term> 
			 <listitem> 
				<para>The filter is the search query to run to get data for the view. </para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Search base</term> 
			 <listitem> 
				<para>This tells the plugin where to start searching for entries matching the filter
				in the directory. If nothing is specified then the directory root is used by default.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Encryption</term> 
			 <listitem> 
				<para>Specified the level of encryption to use for the connection.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Server Type</term> 
			 <listitem> 
				<para>Defines what kind of software the LDAP server is running.</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
		</sect3>

		<sect3 id="lat-pref-profiles-attribute-viewers">
		<title>Attribute Viewers</title>
		<para>This section allows the user to specify what attribute viewers are active for this profile.
		These plugins are are used in the browser view to display and/or edit non-text values</para>
		</sect3>
	</sect2>
  </sect1>

<!-- ================ Views ================================ -->
  <sect1 id="lat-views"> 
	 <title>Views</title>

<!-- ============= View Plugins  ======================== -->
	 <sect2 id="lat-view-plugins"> 
		<title>View plugins</title>
		<para><application>&app;</application> uses plugins to present different views of the data
		on the server to you. By default <application>&app;</application> comes with the following plugins:</para>

		<itemizedlist> 
		<listitem><para>Computers</para></listitem>
 		<listitem><para>Contacts</para></listitem>
		<listitem><para>Groups</para></listitem>
		<listitem><para>Users</para></listitem>
		</itemizedlist>
	 </sect2>

<!-- ============= To create a custom server view or attribute viewer  ======================== -->
	 <sect2 id="lat-view-custom-view"> 
		<title>To create a custom view</title>
		<para>To create a custom view you need to write your own view plugin. You can do this
		using C#. You need to implement the ViewPlugin or AttributeViewPlugin interface. You
		can use pkg-config on lat-plugins to get the necessary compile information.</para>
		<para>Plugins are run from the system plugin directory or the user's
		~/.lat/plugins directory.</para>
	 </sect2>

<!-- ============= To browse and LDAP server  ======================== -->
	 <sect2 id="lat-view-browser"> 
		<title>To browse and LDAP server</title>
		<para>If you want to just browse an LDAP directory, choose <menuchoice><guimenu>View</guimenu><guimenuitem>Browser</guimenuitem></menuchoice>.</para>
		<para>You will switch to the browser view where you can collapse/expand different parts of the tree.  Clicking on an entry will show it's attributes.  You can double click and make edits to different attributes.  To save any chances click on the Apply button in the Output window.</para>
	 </sect2>

<!-- ============= To search an LDAP server  ======================== -->
	 <sect2 id="lat-view-search"> 
		<title>To search an LDAP server</title>
		<para>To search for an entry contained in an LDAP directory, choose <menuchoice><guimenu>View</guimenu><guimenuitem>Search</guimenuitem></menuchoice>.</para>
		<para>In the search view you can enter a search filter or click on the help button andu use the search builder.  Select where you would like to start the search and then click on the Start Search button. The results will appear below</para>
	 </sect2>

<!-- ============= To broswe an LDAP server schema  ======================== -->
	 <sect2 id="lat-view-schema"> 
		<title>To broswe an LDAP server schema</title>
		<para>To browse the LDAP directory's schema, choose <menuchoice><guimenu>View</guimenu><guimenuitem>Schema</guimenuitem></menuchoice>.</para>
	 </sect2>

<!-- ============= To view/edit an entry's properties  ======================== -->
	 <sect2 id="lat-view-properties"> 
		<title>To view/edit an entry's properties</title>
		<para>To view and/or edit and entry's properties, choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Properties</guimenuitem></menuchoice>.</para>
		<para>You can also right click on an entry and select properties or just double click on it.</para>
	 </sect2>

<!-- ============= Show all attributes  ======================== -->
	 <sect2 id="lat-view-all-attributes"> 
		<title>To show all attributes</title>
		<para>In the browser view, to see all possible attributes for an entry, choose <menuchoice><guimenu>View</guimenu><guimenuitem>Show all attributes</guimenuitem></menuchoice>.</para>
	 </sect2>

<!-- ============= To refresh a view  ======================== -->
	 <sect2 id="lat-view-refresh"> 
		<title>To refresh a view</title>
		<para>To refresh your view, choose <menuchoice><guimenu>View</guimenu><guimenuitem>Refresh</guimenuitem></menuchoice>.</para>
	 </sect2>

  </sect1>

<!-- ================ Files ================================ -->
  <sect1 id="lat-files"> 
	 <title>Files</title>

<!-- ============= profiles.xml  ======================== -->
	 <sect2 id="lat-files-profiles"> 
		<title>profiles.xml</title>
		<para>$HOME/.lat/profiles.xml</para>
		<para>Contains the users saved connection profiles. Passwords are stored in the users' GNOME keyring database.</para>
	</sect2>

<!-- ============= templates.dat  ======================== -->
	 <sect2 id="lat-files-templates"> 
		<title>templates.dat</title>
		<para>$HOME/.lat/templates.dat</para>
		<para>Contains information on the users new entry templates.</para>
	</sect2>

<!-- ============= plugins.state  ======================== -->
	 <sect2 id="lat-files-plugin-state"> 
		<title>plugins.state</title>
		<para>$HOME/.lat/plugins.state</para>
		<para>Contains the user configuration for LAT plugins.</para>
	</sect2>
  </sect1>

</article>