path: root/helps/ldapbrowser.help/src/main/docbook/2.40_tools_newconnection_wizard.xml

<!--
  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.
-->
<section id="tools_newconnection_wizard">
	<title>New Connection wizard</title>
	<para>
		This wizard helps you to create a new connection to a LDAP
		directory.
	</para>

	<para>
		To start the wizard choose one of the following options:
		<itemizedlist>
			<listitem>
				<para>
					In the Connections view select the
					<inlinemediaobject>
						<imageobject>
							<imagedata scale="50"
								fileref="icons/connection_add.gif" format="GIF" />
						</imageobject>
					</inlinemediaobject>
					<emphasis role="strong">New Connection...</emphasis>
					button or select
					<emphasis role="strong">New Connection...</emphasis>
					from the context menu.
				</para>
			</listitem>
			<listitem>
				<para>
					In the Workbench window's toolbar, activate the
					drop-down menu on the New Wizard button and select
					<emphasis role="strong">LDAP Connection</emphasis>
				</para>
			</listitem>
			<listitem>
				<para>
					In the Workbench menu bar select
					<emphasis role="strong">
						File > New > LDAP Connection
					</emphasis>
					.
				</para>
			</listitem>
		</itemizedlist>
	</para>

	<para>
		The creation of a new LDAP connection is a four-step process:
		<orderedlist numeration="arabic">
			<listitem>
				<para>
					<link linkend="tools_newconnection_wizard_1">
						Define network parameters.
					</link>
				</para>
			</listitem>
			<listitem>
				<para>
					<link linkend="tools_newconnection_wizard_2">
						Define authentication parameters.
					</link>
				</para>
			</listitem>
			<listitem>
				<para>
					<link linkend="tools_newconnection_wizard_3">
						Define additional browser options (optional).
					</link>
				</para>
			</listitem>
			<listitem>
				<para>
					<link linkend="tools_newconnection_wizard_4">
						Define additional edit options (optional).
					</link>
				</para>
			</listitem>
		</orderedlist>
	</para>

	<simplesect id="tools_newconnection_wizard_1">
		<title>Page 1</title>
		<para>
			The first page allows you to enter a connnection name and
			the network parameters.
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_newconnection_wizard_1.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			<informaltable frame="all">
				<tgroup cols="3">
					<colspec colname="Option" colwidth="1*" />
					<colspec colname="Description" colwidth="2*" />
					<colspec colname="Default" colwidth="1*" />
					<thead>
						<row>
							<entry>Option</entry>
							<entry>Description</entry>
							<entry>Default</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Connection name</entry>
							<entry>
								The name of the connection. In the
								Connections view the connection is
								listed with this name. The name must be
								unique.
							</entry>
							<entry>empty</entry>
						</row>
						<row>
							<entry>Hostname</entry>
							<entry>
								The hostname or IP address of the LDAP
								server. A history of recently used
								hostnames is available through the
								drop-down list.
							</entry>
							<entry>empty</entry>
						</row>
						<row>
							<entry>Port</entry>
							<entry>
								The port of the LDAP server. The default
								port for non-encyrpted connections is
								389. The default port for ldaps://
								connections is 636. A history of
								recently used ports is available through
								the drop-down list.
							</entry>
							<entry>389</entry>
						</row>
						<row>
							<entry>Encryption method</entry>
							<entry>
								The encryption to use. Possible values
								are 'No encrypton', 'ldaps://' and
								'StartTLS extension'.
							</entry>
							<entry>No encryption</entry>
						</row>
						<row>
							<entry>Check network parameter</entry>
							<entry>
								Use this function if you want validate that the
								entered information is correct and the server
								is reachable.
							</entry>
							<entry>-</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>
	</simplesect>

	<simplesect id="tools_newconnection_wizard_2">
		<title>Page 2</title>
		<para>
			On the second page you could specify the authentication
			parameters.
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_newconnection_wizard_2.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			<informaltable frame="all">
				<tgroup cols="3">
					<colspec colname="Option" colwidth="1*" />
					<colspec colname="Description" colwidth="2*" />
					<colspec colname="Default" colwidth="1*" />
					<thead>
						<row>
							<entry>Option</entry>
							<entry>Description</entry>
							<entry>Default</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Authentication Method</entry>
							<entry>
								Select your authentication method between:
								<itemizedlist spacing="normal" mark="bullet">
									<listitem>Anonymous Authentication: connects to the directory without authentication.</listitem>
									<listitem>Simple Authentication: uses simple authentication using a bind DN and password, the credentials are transmitted in clear-text over the network.</listitem>
									<listitem>CRAM-MD5 (SASL): authenticates to the directory using a challenge-response authentication mechanism, the credentials are not transmitted in clear-text over the network.</listitem>
									<listitem>DIGEST-MD5 (SASL): another challenge-response authentication mechanism, additionally you could define your realm and QoP parameters.</listitem>
									<listitem>GSSAPI (Kerberos): users Kerberos based authentication, additional parameters could be defined.</listitem>
								</itemizedlist>
							</entry>
							<entry>Simple Authentication</entry>
						</row>
						<row>
							<entry>Bind DN or user</entry>
							<entry>
								The distinguished name or user ID used to bind.
								Previously entered DNs could be selected
								from drop-down list.
							</entry>
							<entry>empty</entry>
						</row>
						<row>
							<entry>Bind Password</entry>
							<entry>The password used to bind.</entry>
							<entry>empty</entry>
						</row>
						<row>
							<entry>Save password</entry>
							<entry>
								If checked the password will be saved in
								configuration. If not checked you have
								to enter the password whenever you
								connect to the server. Warning: The
								password is saved as plain text!
							</entry>
							<entry>checked</entry>
						</row>
						<row>
							<entry>Check Authentication</entry>
							<entry>
								Use this function if you want to attempt
								a connection plus a bind to the host
								upon completion of the wizard to
								validate that the entered information is
								correct.
							</entry>
							<entry>-</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>
		<para>
			Additional authentication parameters for SASL and Kerberos:
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_newconnection_wizard_2b.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			<informaltable frame="all">
				<tgroup cols="3">
					<colspec colname="Option" colwidth="1*" />
					<colspec colname="Description" colwidth="2*" />
					<colspec colname="Default" colwidth="1*" />
					<thead>
						<row>
							<entry>Option</entry>
							<entry>Description</entry>
							<entry>Default</entry>
						</row>
					</thead>
					<tbody>						
						<row>
							<entry>SASL Realm</entry>
							<entry>The SASL Relam used to bind, only applicaple if DIGEST-MD5 is choosen.</entry>
							<entry>empty</entry>
						</row>
						<row>
							<entry>Quality of Protection</entry>
							<entry>The QoP to use: authentication only, with integrity protection, 
							and with privacy protection</entry>
							<entry>Authentication only</entry>
						</row>
						<row>
							<entry>Protection Strength</entry>
							<entry>The protection strength to use</entry>
							<entry>High</entry>
						</row>
						<row>
							<entry>Mutual Authentication</entry>
							<entry>If checked mutual authentication is used, 
							that means the server has to authenticate itself
							to the client. If unchecked only the client
							authenticates itself to the server.</entry>
							<entry>unchecked</entry>
						</row>
						<row>
							<entry>Use native TGT</entry>
							<entry>If checked the native credential cache
							is used, thus no additional authentication is
							necessary. Note that on Windows systems that
							requires a modification of the registry.</entry>
							<entry>checked</entry>
						</row>
						<row>
							<entry>Object TGT from KDC</entry>
							<entry>If checked a new TGT is obtained from
							the KDC. Username and password must be 
							provided.</entry>
							<entry>unchecked</entry>
						</row>
						<row>
							<entry>Use native system configuration</entry>
							<entry>If checked the native Kerberos configuration
							is used (e.g. /etc/krb5.conf).</entry>
							<entry>checked</entry>
						</row>
						<row>
							<entry>Use configuration file</entry>
							<entry>If checked a custom configuration file
							could be used.</entry>
							<entry>unchecked</entry>
						</row>
						<row>
							<entry>Use following configuration</entry>
							<entry>If checked the Kerberos configuration
							parameters (realm, host, port) could be set
							in the dialog.</entry>
							<entry>unchecked</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>
	</simplesect>

	<simplesect id="tools_newconnection_wizard_3">
		<title>Page 3</title>
		<para>
			On the third page you could enter additional browser options .
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_newconnection_wizard_3.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			<informaltable frame="all">
				<tgroup cols="3">
					<colspec colname="Option" colwidth="1*" />
					<colspec colname="Description" colwidth="2*" />
					<colspec colname="Default" colwidth="1*" />
					<thead>
						<row>
							<entry>Option</entry>
							<entry>Description</entry>
							<entry>Default</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Get base DNs from Root DSE</entry>
							<entry>
								If checked the base DNs are fetched from
								namingContexts attribute of the Root
								DSE.
							</entry>
							<entry>checked</entry>
						</row>
						<row>
							<entry>Fetch Base DNs</entry>
							<entry>
								Use this function to get the
								namingContext values from the Root DSE.
								The returned values will appear in the
								'Base DN' drop-down list.
							</entry>
							<entry>-</entry>
						</row>
						<row>
							<entry>Base DN</entry>
							<entry>
								The base DN to use. You may enter a DN
								manually or you may select one from the
								drop-down list. This field is only
								enabled if the option 'Get base DNs from
								root DSE' is off.
							</entry>
							<entry>empty</entry>
						</row>
						<row>
							<entry>Count Limit</entry>
							<entry>
								Maximum number of entries returned from
								server when browsing the directory, it
								is also used as default value when
								searching the directory. A value of 0
								means no count limit. Note that this
								value is a client-side value, its
								possible that also a server-side limit
								is used.
							</entry>
							<entry>1000</entry>
						</row>
						<row>
							<entry>Time Limit</entry>
							<entry>
								The maximum time in seconds the
								server searches for results. This is
								used as default value when browsing or
								searching the directory. A value of 0
								means no limit. Note that this value is
								a client-side value, its possible that
								also a server-side limit is used.
							</entry>
							<entry>0</entry>
						</row>
						<row>
							<entry>Alias Dereferencing</entry>
							<entry>
								Specifies whether aliases should be
								dereferenced while finding the search base
								entry or when performing the search or
								both.
								To manage (create, modify, delete) alias
								objects you have to uncheck both options. 
								</entry>
							<entry>Both finding and searching</entry>
						</row>
						<row>
							<entry>Referrals Handling</entry>
							<entry>
								Specifies the referral handling. 
								
								<itemizedlist spacing="normal" mark="bullet">
									<listitem>Follow Referrals manually:
									Received referrals and search continuations are just displayed 
									in the Browser. As soon as you open or expand such an search 
									continuation the search is continued. You are asked which connection 
									you want to use to follow a specific referral URL, this way you have 
									full control regarding encryption and authentication options when 
									following referrals.</listitem>
									<listitem>Follow Referrals automatically: 
									Follows referrals and search continuations immediately if they are 
									received from the directory server. You are asked which connection 
									you want to use to follow a specific referral URL, this way you 
									have full control regarding encryption and authentication options 
									when following referrals.</listitem>
									<listitem>Ignore Referrals:
									Any referral or search continuation received from the directory server 
									is silently ignored. No error is logged, no dialog appears, no special 
									entry is displayed in the DIT, no ManageDsaIT control is sent to the 
									server.</listitem>
								</itemizedlist>
							</entry>
							<entry>Follow Referrals manually</entry>
						</row>
						<row>
							<entry>Use ManageDsaIT control while browsing</entry>
							<entry>
								If enabled the ManageDsaIT control is sent to the server in each request. 
								This signals the directory server to not send referrals and search 
								continuations, but return the special referral objects. This only works 
								if the directory server supports the ManageDsaIT control.
							</entry>
							<entry>unchecked</entry>
						</row>
						
						<row>
							<entry>Fetch subentries while browsing</entry>
							<entry>
								If enabled enabled both, normal and subentries 
								according to RFC 3672 are fetched. This causes 
								additional search requests while browsing the
								directory.
							</entry>
							<entry>unchecked</entry>
						</row>
						<row>
							<entry>Paged Search</entry>
							<entry>
								If enabled the simple paged result control is used
								while browsing the directory. 
								With the page size you could define how many entries 
								should be retrieved	in one request. 
								If Scroll Mode is enabled only one page is fetched
								from the server at once while browsing, you could 
								'scroll' through the pages by using the 'next page' 
								and 'top page' items. If disabled 
								<emphasis role="strong">all</emphasis>
								entries are fetched from the server, the paged 
								result control is only used in background to 
								avoid server-side limits.
							</entry>
							<entry>unchecked</entry>
						</row>
						<row>
							<entry>Fetch operational attributes while browsing</entry>
							<entry>
								If enabled enabled both, user attributes and
								operational attributes are retrieved while browsing.
								If the server supports the feature 
								'All Operational Attributes' then a '+' is used to 
								retrieve operational attributes, otherwise all
								operational attributes defined in the schema are 
								requested.
							</entry>
							<entry>unchecked</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>
	</simplesect>
	
	<simplesect id="tools_newconnection_wizard_4">
		<title>Page 4</title>
		<para>
			On the fourth page you could enter additional edit options.
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_newconnection_wizard_4.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			<informaltable frame="all">
				<tgroup cols="3">
					<colspec colname="Option" colwidth="1*" />
					<colspec colname="Description" colwidth="2*" />
					<colspec colname="Default" colwidth="1*" />
					<thead>
						<row>
							<entry>Option</entry>
							<entry>Description</entry>
							<entry>Default</entry>
						</row>
					</thead>
					<tbody>
						<row>
							<entry>Modify Mode</entry>
							<entry>
								Specify the modify mode for attributes with an equality matching rule.
								Description of options:
								<itemizedlist spacing="normal" mark="bullet">
									<listitem>Optimized Modify Operations: uses add/delete by default, 
									uses replace if operation count is less</listitem>
									<listitem>Always REPLACE: always uses replace operations to perform 
									entry modifications</listitem>
									<listitem>Always ADD/DELETE: always uses add and/or delete operations 
									to perform entry modifications</listitem>
								</itemizedlist>
							</entry>
							<entry>Optimized Modify Operations</entry>
						</row>
						<row>
							<entry>Modify Mode (no equality matching rule)</entry>
							<entry>
								Specify the modify mode for attributes with *no* equality matching rule.
								Description of options:
								<itemizedlist spacing="normal" mark="bullet">
									<listitem>Optimized Modify Operations: uses add/delete by default, 
									uses replace if operation count is less</listitem>
									<listitem>Always REPLACE: always uses replace operations to perform 
									entry modifications</listitem>
									<listitem>Always ADD/DELETE: always uses add and/or delete operations 
									to perform entry modifications</listitem>
								</itemizedlist>
								Recommended values for various LDAP servers:
								<itemizedlist spacing="normal" mark="bullet">
									<listitem>ApacheDS: Optimized Modify Operations or REPLACE</listitem>
									<listitem>OpenLDAP: REPLACE</listitem>
									<listitem>OpenDS / SunDSEE: Optimized Modify Operations or REPLACE</listitem>
									<listitem>FedoraDS / 389DS: Optimized Modify Operations 
									(missing equality matching rules for many standard attribute types)</listitem>
									<listitem>Active Directory: Optimized Modify Operations 
									(exposes no equality matching rules at all)</listitem>
									<listitem>eDirectory: Optimized Modify Operations 
									(exposes no equality matching rules at all)</listitem>
								</itemizedlist>
							</entry>
							<entry>Optimized Modify Operations</entry>
						</row>
						<row>
							<entry>Modify Order</entry>
							<entry>
								Specify the modify order when using add and delete operations.
							</entry>
							<entry>Delete first</entry>
						</row>
					</tbody>
				</tgroup>
			</informaltable>
		</para>
	</simplesect>

</section>