<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->
<chapter id="gettingstarted">
	<title>Getting started</title>
	
	<para>
		This getting started guide provides a brief introduction to the Apache Directory Studio Browser. 
	</para>
	
	<section id="gettingstarted_download_install">
		<title>Download and installation</title>
	<para>
		The latest version of Apache Directory Studio can be downloaded
		from the Apache Directory Studio Downloads page, at this address
		:
		<ulink
			url="https://directory.apache.org/studio/downloads.html">
			https://directory.apache.org/studio/downloads.html
		</ulink>
		.
	</para>
	<para>
		The download page also includes the installation instructions.
	</para>

	</section>
	
	<section id="gettingstarted_open_perspecitve">
		<title>Open LDAP perspective</title>
		<para>
			To use the Apache Directory Studio Browser plug-in open the LDAP perspective. Therefore go to
			<emphasis role="strong">
			<menuchoice>
				<guimenu>Window</guimenu>
				<guisubmenu>Open Perspective</guisubmenu>
				<guimenuitem>Other...</guimenuitem>
			</menuchoice>
			</emphasis>
			and select the <emphasis role="strong">LDAP</emphasis> perspective.
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/gettingstarted_open_perspective_1.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			For more information about the LDAP perspective see <link linkend="tools_ldap_perspective">LDAP perspective</link>
		</para>
	</section>

	<section id="gettingstarted_create_connection">
		<title>Create connection</title>
		<para>
			The bottom left corner shows all of the LDAP connections. As can be seen, the view is empty, meaning a connection still needs to be specified.
		</para>
		<para>
			To create a new connection click the 
			<inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/connection_add.gif" format="GIF"/></imageobject></inlinemediaobject> 
			<emphasis role="strong">New Connection</emphasis> button.
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/gettingstarted_create_connection_1.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			In the wizard's first page enter a connection name as well as the hostname and the port of the LDAP server. To check the connection
			parameter you entered you may click to <emphasis role="strong"><guibutton>Check Network Parameter</guibutton></emphasis>. 
			Click <emphasis role="strong">Next</emphasis> when done.
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/gettingstarted_create_connection_2.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			Here is a list of common directory servers and the ports they use by default:
			<informaltable frame='all' >
				<tgroup cols='2' align='left' colsep='1' rowsep='1'>
					<colspec colname="Directory Server" align="left" colwidth="3*" />
					<colspec colname="Default Port" align="right" colwidth="1*" />
					<thead>
						<row>
						  <entry>Directory Server</entry>
						  <entry>Default Port</entry>
						</row>
					</thead>
					<tbody>
						<row>
						  <entry>Apache Directory Server</entry>
						  <entry>10389</entry>
						</row>
						<row>
						  <entry>OpenDS</entry>
						  <entry>1389</entry>
						</row>
						<row>
						  <entry>OpenLDAP, Fedora, Sun, Active Directory</entry>
						  <entry>389</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>
		<para>
			In the wizard's second page select the authentication method. If you choose the simple bind method also enter your bind DN or user and bind password. 
			To check the authentication	parameter you entered you may click to <emphasis role="strong"><guibutton>Check Authentication</guibutton></emphasis>. 
			Click <emphasis role="strong">Finish</emphasis> when done.
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/gettingstarted_create_connection_3.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			Here is a list of common directory servers and the administrator's bind DN and password they use by default:
			<informaltable frame='all' >
				<tgroup cols='3' align='left' colsep='1' rowsep='1'>
					<colspec colname="Directory Server" align="left" colwidth="3*" />
					<colspec colname="Default Bind DN" align="left" colwidth="1*" />
					<colspec colname="Default Bind Password" align="left" colwidth="1*" />
					<thead>
						<row>
						  <entry>Directory Server</entry>
						  <entry>Default Bind DN</entry>
						  <entry>Default Bind Password</entry>
						</row>
					</thead>
					<tbody>
						<row>
						  <entry>Apache Directory Server</entry>
						  <entry>uid=admin,ou=system</entry>
						  <entry>secret</entry>
						</row>
						<row>
						  <entry>OpenDS, Sun, Fedora</entry>
						  <entry>cn=Directory Manager</entry>
						  <entry>specified at setup</entry>
						</row>
						<row>
						  <entry>OpenLDAP</entry>
						  <entry>specified at setup, see slapd.conf</entry>
						  <entry>specified at setup, see slapd.conf</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>		
		<para>
			Observe that the <emphasis role="strong">Connections view</emphasis> now shows the created connection.
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/gettingstarted_create_connection_4.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			For more information see <link linkend="tools_connections_view">Connections view</link>
		</para>			
	</section>
	
	<section  id="gettingstarted_browse">
		<title>Browse the directory</title>
		<para>
			The <emphasis role="strong">LDAP Browser view</emphasis> is on the top left. 
			The category <inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/dit.gif" format="GIF"/></imageobject></inlinemediaobject>
			<emphasis role="strong">DIT</emphasis> shows the hierarchical content of the directory. You may expand and collapse the tree.
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata width="15cm"
							fileref="images/gettingstarted_browse_1.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			When selecting an entry its attributes and values will be displayed in an <emphasis role="strong">Entry editor</emphasis>.
		</para>
		<para>
			For more information see <link linkend="tools_browser_view">LDAP Browser view</link> and <link linkend="tools_entry_editosr">Entry editors</link>.
		</para>	
	</section>
	
	<section  id="gettingstarted_search">
		<title>Search the directory</title>
		<para>
			For a basic search you could use the <link linkend="tools_browser_view_quicksearch">Quick Search</link>.
		</para>
		<para>
			For a more advanced serach you may use the search function. 
		</para>
		<orderedlist numeration="arabic">
			<listitem>
				<para>
					In the toolbar click the 
					<inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/search.gif" format="GIF"/></imageobject></inlinemediaobject>
					<emphasis role="strong">Search</emphasis> button.
				</para>
			</listitem>
			
			<listitem>
				<para>
					If it is not already selected, select the 
					<inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/browser_searchresulteditor.gif" format="GIF"/></imageobject></inlinemediaobject>
					<emphasis role="strong">LDAP Search</emphasis> tab.
				</para>
				<para>
					<screenshot>
						<mediaobject>
							<imageobject>
								<imagedata scale="50"
									fileref="images/gettingstarted_search_1.png" format="PNG" />
							</imageobject>
						</mediaobject>
					</screenshot>
				</para>
				<para>
					In the search dialog type in a search name. Select a connection to search on and the search base DN. 
					Specify a valid LDAP filter and the returning attributes as comma separated	list, hit Ctrl-Space to get content assistance. 
					Additionally you may choose scope, limits, alias and referral options.
				</para>
			</listitem>

			<listitem>
				<para>
					Press the <emphasis role="strong">Search</emphasis> button.
				</para>
			</listitem>

			<listitem>
				<para>
					The category <inlinemediaobject><imageobject><imagedata scale="50" fileref="icons/searches.gif" format="GIF"/></imageobject></inlinemediaobject>
					<emphasis role="strong">Searches</emphasis> in the LDAP Browser shows the searches. You may expand the search to see all search result enties.
				</para>
				<para>
					<screenshot>
						<mediaobject>
							<imageobject>
								<imagedata width="15cm"
									fileref="images/gettingstarted_search_2.png" format="PNG" />
							</imageobject>
						</mediaobject>
					</screenshot>
				</para>			
				<para>
					When selecting a search the search results and returning attributes will be displayed in the <emphasis role="strong">Search Result editor</emphasis>.
				</para>
				<para>
					When selecting a search result entry its attributes and values will be displayed in the <emphasis role="strong">Entry editor</emphasis>.
				</para>
			</listitem>
			
		</orderedlist>
		
		<para>
			For more information see <link linkend="tools_browser_view">LDAP Browser view</link> and <link linkend="tools_search_result_editor">Search Result editor</link>.
		</para>	
	</section>
	
</chapter>
