<!--
  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_connection_properties">
	<title>Connection properties</title>
	<para>
		The following properties can be modified on the Connection
		properties pages:
	</para>
	<simplesect id="tools_connection_properties_network_parameter">
		<title>Network Parameter</title>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_1.png"
							format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<informaltable frame='all'>
			<tgroup cols='2'>
				<colspec colname="Field" colwidth="1*" />
				<colspec colname="Description" colwidth="2*" />
				<thead>
					<row>
						<entry>Field</entry>
						<entry>Description</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>
					</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>
					</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>
					</row>
					<row>
						<entry>Encryption method</entry>
						<entry>
							The encryption to use. Possible values are
							'No encrypton', 'ldaps://' and 'StartTLS
							extension'.
						</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>
					</row>
				</tbody>
			</tgroup>
		</informaltable>
	</simplesect>
	<simplesect id="tools_connection_properties_authentication">
		<title>Authentication</title>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_2.png"
							format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<informaltable frame='all'>
			<tgroup cols='2'>
				<colspec colname="Field" colwidth="1*" />
				<colspec colname="Description" colwidth="2*" />
				<thead>
					<row>
						<entry>Field</entry>
						<entry>Description</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>
					</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>
					</row>
					<row>
						<entry>Bind Password</entry>
						<entry>The password used to bind.</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>
					</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>
					</row>
				</tbody>
			</tgroup>
		</informaltable>
		<para>
			Additional authentication parameters for SASL and Kerberos:
		</para>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_2b.png" format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<informaltable frame="all">
			<tgroup cols="2">
				<colspec colname="Field" colwidth="1*" />
				<colspec colname="Description" colwidth="2*" />
				<thead>
					<row>
						<entry>Option</entry>
						<entry>Description</entry>
					</row>
				</thead>
				<tbody>						
					<row>
						<entry>SASL Realm</entry>
						<entry>The SASL Relam used to bind, only applicaple if DIGEST-MD5 is choosen.</entry>
					</row>
					<row>
						<entry>Quality of Protection</entry>
						<entry>The QoP to use: authentication only, with integrity protection, 
						and with privacy protection</entry>
					</row>
					<row>
						<entry>Protection Strength</entry>
						<entry>The protection strength to use</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>
					</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>
					</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>
					</row>
					<row>
						<entry>Use native system configuration</entry>
						<entry>If checked the native Kerberos configuration
						is used (e.g. /etc/krb5.conf).</entry>
					</row>
					<row>
						<entry>Use configuration file</entry>
						<entry>If checked a custom configuration file
						could be used.</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>
					</row>
				</tbody>
			</tgroup>
		</informaltable>
	</simplesect>
	<simplesect id="tools_connection_properties_browser_options">
		<title>Browser Options</title>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_3.png"
							format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<informaltable frame='all'>
			<tgroup cols='2'>
				<colspec colname="Field" colwidth="1*" />
				<colspec colname="Description" colwidth="2*" />
				<thead>
					<row>
						<entry>Field</entry>
						<entry>Description</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>
					</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>
					</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>
					</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>
					</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>
					</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>
					</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>
					</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>
					</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>
					</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>
					</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>
					</row>
				</tbody>
			</tgroup>
		</informaltable>
	</simplesect>
	<simplesect id="tools_connection_properties_edit_options">
		<title>Edit Options</title>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_3b.png"
							format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<informaltable frame='all'>
			<tgroup cols='2'>
				<colspec colname="Field" colwidth="1*" />
				<colspec colname="Description" colwidth="2*" />
				<thead>
					<row>
						<entry>Field</entry>
						<entry>Description</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>Default: uses add/delete by default, 
								uses replace for X-ORDERED attributes</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>
					</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>Default: uses add/delete by default, 
								uses replace for X-ORDERED attributes</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: Default or REPLACE</listitem>
								<listitem>OpenLDAP: REPLACE</listitem>
								<listitem>OpenDS / SunDSEE: Default or REPLACE</listitem>
								<listitem>FedoraDS / 389DS: Default 
								(missing equality matching rules for many standard attribute types)</listitem>
								<listitem>Active Directory: Default 
								(exposes no equality matching rules at all)</listitem>
								<listitem>eDirectory: Default 
								(exposes no equality matching rules at all)</listitem>
							</itemizedlist>
						</entry>
					</row>
					<row>
						<entry>Modify Order</entry>
						<entry>
							Specify the modify order when using add and delete operations.
						</entry>
					</row>
				</tbody>
			</tgroup>
		</informaltable>
	</simplesect>
	<simplesect id="tools_connection_properties_rootdse">
		<title>Root DSE</title>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_4.png"
							format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			The Root DSE properties page provides information about the
			connected directory server like directory type and version,
			controls, extensions and features.
		</para>
	</simplesect>
	<simplesect id="tools_connection_properties_schema">
		<title>Schema</title>
		<para>
			<screenshot>
				<mediaobject>
					<imageobject>
						<imagedata scale="50"
							fileref="images/tools_connection_properties_5.png"
							format="PNG" />
					</imageobject>
				</mediaobject>
			</screenshot>
		</para>
		<para>
			The Schema properties page provides some information about
			the schema. The 'Schema Information' group shows the schema
			DN an modification timestamp. With the 'Reload Schema'
			button a schema reload could be forced, the schema is
			reloaded automatically if the directory's schema is newer
			than the cached one. The 'Schema Cache' group shows
			information about the cached schema.
		</para>
	</simplesect>
</section>
