You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@directory.apache.org by fe...@apache.org on 2010/08/13 17:20:29 UTC
svn commit: r985236 - in
/directory/sandbox/felixk/apacheds-docs/src/basic-user-guide:
chapter-how-to-begin.xml chapter_basic_security.xml
Author: felixk
Date: Fri Aug 13 15:20:28 2010
New Revision: 985236
URL: http://svn.apache.org/viewvc?rev=985236&view=rev
Log:
Replace various <programlisting> by <screen>, as it's a screen input or output
Modified:
directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter-how-to-begin.xml
directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter_basic_security.xml
Modified: directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter-how-to-begin.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter-how-to-begin.xml?rev=985236&r1=985235&r2=985236&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter-how-to-begin.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter-how-to-begin.xml Fri Aug 13 15:20:28 2010
@@ -1,22 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
-<!--
-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.
--->
+<!-- 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
version="5.0"
xmlns="http://docbook.org/ns/docbook"
@@ -1356,14 +1345,14 @@ log4j.logger.org.apache.directory.shared
</para>
<example>
<title>Log file location Linux/MacOS/Solaris</title>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$DAEMON_HOME/apacheds \
...
-outfile $SERVER_HOME/var/log/apacheds-stdout.log \
-errfile $SERVER_HOME/var/log/apacheds-stderr.log \
...
$APACHEDS_HOME start
- ]]></programlisting>
+ ]]></screen>
</example>
</section>
<section
@@ -1469,7 +1458,7 @@ log4j.appender.R.layout.ConversionPatter
]]></programlisting>
<para>Some examples lines within the log file, formatted with the pattern "[%d{HH:mm:ss}] %p [%c] - %m%n" are:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
...
[12:29:03] WARN [org.apache.directory.server.core.DefaultDirectoryService]
- You didn't change the admin password of directory service instance 'default'.
@@ -1479,7 +1468,7 @@ log4j.appender.R.layout.ConversionPatter
- Successful bind of an LDAP Service (636) is complete.
[12:29:05] INFO [org.apache.directory.server.Service] - server: started in 6750 milliseconds
...
- ]]></programlisting>
+ ]]></screen>
<para>The pattern uses the following conversion characters:</para>
<table
id="Log file output patterns">
@@ -1531,13 +1520,13 @@ log4j.appender.R.layout.ConversionPatter
log4j.appender.R.layout.ConversionPattern=[%d{dd.MM.yyyy HH:mm:ss}] %p: %c{1}.%M() - %m%n
]]></programlisting>
<para>leads to messages of this form:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
...
[29.12.2006 13:50:44] INFO: ServerContextFactory.startLDAP0()
- Successful bind of an LDAP Service (636) is complete.
[29.12.2006 13:50:44] INFO: Service.init() - server: started in 3016 milliseconds
...
- ]]></programlisting>
+ ]]></screen>
<caution>
<para>"Generating caller location information like with %M or %L is extremely slow. Its use should be
avoided unless execution speed is not an issue." (from the log4j documentation)</para>
Modified: directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter_basic_security.xml
URL: http://svn.apache.org/viewvc/directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter_basic_security.xml?rev=985236&r1=985235&r2=985236&view=diff
==============================================================================
--- directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter_basic_security.xml (original)
+++ directory/sandbox/felixk/apacheds-docs/src/basic-user-guide/chapter_basic_security.xml Fri Aug 13 15:20:28 2010
@@ -1,22 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
-<!--
-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.
--->
+<!-- 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
version="5.0"
xmlns="http://docbook.org/ns/docbook"
@@ -124,15 +113,15 @@ userpassword: pass
]]></programlisting>
<para>In the following search command, a user tries to bind with the given DN (option -D) but a wrong password
(option -w). The bind fails and the command terminates without performing the search.</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
-w wrong -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
ldap_simple_bind: Invalid credentials
ldap_simple_bind: additional info: Bind failed: null
- ]]></programlisting>
+ ]]></screen>
<para>If the user provides the correct password during the call of the ldapsearch command, the bind operation
succeeds and the seach operation is performed afterwards.</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
-w pass -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
version: 1
@@ -141,7 +130,7 @@ ou: people
description: Contains entries which describe persons (seamen)
objectclass: organizationalUnit
objectclass: top
- ]]></programlisting>
+ ]]></screen>
</section>
<section
id="Binds from Java components using JNDI">
@@ -202,10 +191,10 @@ ou=groups: javax.naming.directory.DirCon
<emphasis>NamingException</emphasis>
:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ java SimpleBindDemo "cn=Horatio Hornblower,ou=people,o=sevenSeas" quatsch
[LDAP: error code 49 - Bind failed: null]
- ]]></programlisting>
+ ]]></screen>
<para>
In real life, you obviously want to separate most of the configuration data from the source code, for instance
with the help of the
@@ -319,7 +308,7 @@ public class DigestDemo {
hash function applied, it calculates the hash value of the given password with the appropriate algorithm (this
is why the algorithm is stored together with the hashed password). Afterwards it compares the result with the
stored attribute value. In case of a match, the bind operation ends successfully:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
-w pass -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
version: 1
@@ -328,18 +317,18 @@ ou: people
description: Contains entries which describe persons (seamen)
objectclass: organizationalUnit
objectclass: top
- ]]></programlisting>
+ ]]></screen>
<para>
Providing the hashed value of the
<emphasis>userPassword</emphasis>
attribute instead of the original value will be rejected by ApacheDS:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Hornblower,ou=people,o=sevenSeas" \\
-w "{SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=" -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
ldap_simple_bind: Invalid credentials
ldap_simple_bind: additional info: Bind failed: null
- ]]></programlisting>
+ ]]></screen>
<para>This is intended. If someone was able to catch this value (from an LDIF export for instance), s/he must
still provide the password itself in order to get authenticated.</para>
<warning>
@@ -395,7 +384,7 @@ ldap_simple_bind: additional info: Bind
<title>Example: Server behavior with anonymous binds disabled</title>
<para>Now the same command performed against ApacheDS 1.5 with anonymous access enabled as described above. The
behavior is different â the entry is visible.</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -b "ou=people,o=sevenSeas" -s base "(objectclass=*)"
version: 1
dn: ou=people,o=sevenSeas
@@ -403,7 +392,7 @@ ou: people
description: Contains entries which describe persons (seamen)
objectclass: organizationalUnit
objectclass: top
- ]]></programlisting>
+ ]]></screen>
</section>
<section
id="Other clients">
@@ -636,7 +625,7 @@ public class AdvancedBindDemo {
]]></programlisting>
</example>
<para>Some example calls:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ java AdvancedBindDemo unknown sailor
Authentication failed
@@ -647,7 +636,7 @@ Authentication successful
$ java AdvancedBindDemo hornblo quatsch
dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
[LDAP: error code 49 - Bind failed: null]
- ]]></programlisting>
+ ]]></screen>
<para>
The examples consist of an unknown user (an
<emphasis>inetOrgPerson</emphasis>
@@ -824,7 +813,7 @@ userpassword: bush
<para>Without ACIs the server automatically protects, hides, the admin user from everyone but the admin user.
Here a sample search operation in order to demonstrate this protection. The same command is submitted three
times with different users.</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\
-b "ou=system" -s one "(uid=admin)" dn
version: 1
@@ -837,10 +826,10 @@ $ ldapsearch -h zanzibar -p 10389 -D "cn
-b "ou=system" -s one "(uid=admin)" dn
$
- ]]></programlisting>
+ ]]></screen>
<para>Users cannot see other user entries under the 'ou=users,ou=system' entry. So placing new users there
automatically protects them. Placing new users anywhere else exposes them.</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret \\
-b "ou=users,ou=system" -s one "(objectclass=*)" dn
version: 1
@@ -870,7 +859,7 @@ dn: cn=Cornelius Buckley,ou=people,o=sev
dn: cn=William Bligh,ou=people,o=sevenSeas
...
$
- ]]></programlisting>
+ ]]></screen>
<para>
Groups defined using
<emphasis>groupOfNames</emphasis>
@@ -1170,13 +1159,13 @@ prescriptiveACI: {
]]></programlisting>
<para>To apply this configuration to the sample data partition, you can perform an ldapmodify with the LDIF as
agrument:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapmodify -h zanzibar -p 10389 -D "uid=admin,ou=system" -w secret -f authz_sevenSeas.ldif
modifying entry o=sevenSeas
adding new entry cn=sevenSeasAuthorizationRequirementsACISubentry,o=sevenSeas
$
- ]]></programlisting>
+ ]]></screen>
<para>It is also possible to use graphical tools; some of them offer the feature to perform operations given in
LDIF.</para>
</section>
@@ -1195,7 +1184,7 @@ $
<para>Bind as user "William Bush" and search for entries which match "(uid=hhornblo)". Expected behavior: We are
able to read the attributes of entry "cn=Horatio Hornblower,ou=people,o=sevenSeas" (the only entry which
matches the filter). The password attribute should not be visible. It works as desired: </para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
-b "o=sevenSeas" -s sub "(uid=hhornblo)"
version: 1
@@ -1210,14 +1199,14 @@ uid: hhornblo
givenname: Horatio
description: Capt. Horatio Hornblower, R.N
sn: Hornblower
- ]]></programlisting>
+ ]]></screen>
<para>
In the described configuration, the user "Horatio Nelson" acts as a directory manager below "o=sevenSeas".
Hence he should basically be allowed to do everything. He should even be able to see other users'
<emphasis>userPassword</emphasis>
values. In our case, the hash function SHA was applied to them:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
-b "o=sevenSeas" -s sub "(objectclass=person)
" uid userPassword
@@ -1234,10 +1223,10 @@ dn: cn=Thomas Quist,ou=people,o=sevenSea
userpassword: {SHA}nU4eI71bcnBGqeO0t9tXvY1u5oQ=
uid: tquist
...
- ]]></programlisting>
+ ]]></screen>
<para>But "Horation Nelson" is not able to perform searches in other areas than "o=sevenSeas" to see the
entries. Of course our global ApacheDS administrator "uid=admin,ou=system" is still able to see them:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
-b "ou=system" -s sub "(objectclass=person)"
@@ -1262,7 +1251,7 @@ objectclass: person
objectclass: top
sn: Amos
...
- ]]></programlisting>
+ ]]></screen>
</section>
<section
id="Trying to manipulate data">
@@ -1293,16 +1282,16 @@ mail: jhook@neverland
userpassword: peterPan
]]></programlisting>
<para>An anonymous user is not allowed to create new entries, as the following error message shows:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapmodify -h zanzibar -p 10389 -a -f captain_hook.ldif
adding new entry cn=James Hook,ou=people,o=sevenSeas
ldap_add: Insufficient access
ldap_add: additional info: failed to add entry cn=James Hook,ou=people,o=sevenSeas: null
$
- ]]></programlisting>
+ ]]></screen>
<para>The same holds true for all "Seven Seas"-user other than "Horatio Nelson". The latter is permitted to do
so:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapmodify -h zanzibar -p 10389 -D "cn=William Bush,ou=people,o=sevenSeas" -w pass \\
-a -f captain_hook.ldif
adding new entry cn=James Hook,ou=people,o=sevenSeas
@@ -1313,21 +1302,21 @@ $ ldapmodify -h zanzibar -p 10389 -D "cn
-a -f captain_hook.ldif
adding new entry cn=James Hook,ou=people,o=sevenSeas
$
- ]]></programlisting>
+ ]]></screen>
<para>
Afterwards a new entry is successfully created within the "Seven Seas" partition by user "Horatio Nelson".
The '+' sign in the attributes list of the
<emphasis>ldapsearch</emphasis>
command causes ApacheDS to return the operational attributes, which demonstrate this.
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapsearch -h zanzibar -p 10389 -b "o=sevenSeas" -s sub "(cn=James Hook)" +
version: 1
dn: cn=James Hook,ou=people,o=sevenSeas
accessControlSubentries: cn=sevenSeasAuthorizationRequirementsACISubentry,o=sevenSeas
creatorsName: cn=Horatio Nelson,ou=people,o=sevenSeas
createTimestamp: 20061203140109Z
- ]]></programlisting>
+ ]]></screen>
</section>
<section
id="Modifying an entry">
@@ -1353,7 +1342,7 @@ description: Wears an iron hook in place
command line tool again fails for users other than "Horation Nelson" (who is allowed to due to the
authorization configuration) and "uid=admin,ou=system".
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapmodify -h zanzibar -p 10389 -f captain_hook_modify.ldif
modifying entry cn=James Hook,ou=people,o=sevenSeas
ldap_modify: Insufficient access
@@ -1369,7 +1358,7 @@ evenSeas: null
$ ldapmodify -h zanzibar -p 10389 -D "cn=Horatio Nelson,ou=people,o=sevenSeas" -w pass \\
-f captain_hook_modify.ldif
modifying entry cn=James Hook,ou=people,o=sevenSeas
- ]]></programlisting>
+ ]]></screen>
</section>
<section
id="Deleting an entry">
@@ -1393,7 +1382,7 @@ changetype: delete
not permitted to delete Captain Hook's entry. The user "Horatio Nelson", our directory manager for "Seven
Seas", is:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ ldapmodify -h zanzibar -p 10389 -f captain_hook_delete.ldif
deleting entry cn=James Hook,ou=people,o=sevenSeas
ldap_delete: Insufficient access
@@ -1409,7 +1398,7 @@ $ ldapmodify -h zanzibar -p 10389 -D "cn
-f captain_hook_delete.ldif
deleting entry cn=James Hook,ou=people,o=sevenSeas
$
- ]]></programlisting>
+ ]]></screen>
<para>The entry "cn=James Hook,ou=people,o=sevenSeas" has been successfully deleted from the partition. Our
little demonstration on how the ACI subsystem with a realistic configuration behaves end here. Learn more
about it in the Advanced User's Guide.</para>
@@ -1653,7 +1642,7 @@ $
xlink:href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html">manpage</link>
.
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ keytool -genkey -keyalg "RSA" -dname "cn=zanzibar, ou=ApacheDS, o=ASF, c=US" \\
-alias zanzibar -keystore zanzibar.ks -storepass secret -validity 730
Enter key password for <zanzibar>
@@ -1672,7 +1661,7 @@ Your keystore contains 1 entry
zanzibar, Jun 10, 2007, keyEntry,
Certificate fingerprint (MD5): 95:4A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C
$
- ]]></programlisting>
+ ]]></screen>
<para>
Another option is to use graphical tools for key creation like
<link
@@ -1829,7 +1818,7 @@ public class ConnectWithLdaps {
<emphasis>CommunicationException</emphasis>
, if the certificate is not trusted:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ java ConnectWithLdaps
Exception in thread "main" javax.naming.CommunicationException:
simple bind failed: zanzibar:636
@@ -1839,11 +1828,11 @@ Exception in thread "main" javax.naming.
unable to find valid certification path to requested target]
at com.sun.jndi.ldap.LdapClient.authenticate(Unknown Source)
...
-]]></programlisting>
+]]></screen>
<para>In order to make the client trust our server, one option is to share a self signed certificate.
So we
export the certificate (DER format) using keytool like this:</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ keytool -export -keystore zanzibar.ks -alias zanzibar -file zanzibar.cer
Enter keystore password: secret
Certificate stored in file <zanzibar.cer>
@@ -1852,7 +1841,7 @@ total 6
-rw-r--r-- 1 stefan users 504 Jun 10 21:51 zanzibar.cer
-rw-r--r-- 1 stefan users 1275 Jun 10 20:42 zanzibar.ks
$
-]]></programlisting>
+]]></screen>
<para>
Please note that you don't want to share the server keystore file itself with arbitrary clients, because
it
@@ -1865,7 +1854,7 @@ $
<emphasis>zanzibar.cer</emphasis>
like this:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ keytool -import -file zanzibar.cer -alias zanzibar -keystore trusted.ks -storepass secret
Owner: CN=zanzibar, OU=ApacheDS, O=ASF, C=US
Issuer: CN=zanzibar, OU=ApacheDS, O=ASF, C=US
@@ -1885,7 +1874,7 @@ Your keystore contains 1 entry
zanzibar, Jun 11, 2007, trustedCertEntry,
Certificate fingerprint (MD5): 95:4A:90:3D:69:09:64:84:C7:21:FD:F7:B8:82:11:8C
$
-]]></programlisting>
+]]></screen>
<para>Instead of using the command line version of keytool, it is also possible to perform the certificate
export and import operations with Portecle or any other graphical frontend. This is for instance how the
trusted.ks files with the imported certificate looks like in Portecle.</para>
@@ -1904,11 +1893,11 @@ $
<emphasis>trusted.ks</emphasis>
as the trusted store via the environment like this:
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ java -Djavax.net.ssl.trustStore=trusted.ks ConnectWithLdaps
ou=people: javax.naming.directory.DirContext
ou=groups: javax.naming.directory.DirContext
-]]></programlisting>
+]]></screen>
<para>Another option would be to import the certificate in the default keystore of the JRE installation (within
$JAVA_HOME/jre/lib/security). For a test certificate this proceeding is not appropriate.</para>
<section
@@ -1924,7 +1913,7 @@ ou=groups: javax.naming.directory.DirCon
store, the server certificate, and the steps during establishing of the SSL connection
(handshake):
</para>
- <programlisting><![CDATA[
+ <screen><![CDATA[
$ java -Djavax.net.ssl.trustStore=trusted.ks -Djavax.net.debug=ssl ConnectWithLdaps
setting up default SSLSocketFactory
use default SunJSSE impl class: com.sun.net.ssl.internal.ssl.SSLSocketFactoryImpl
@@ -1951,7 +1940,7 @@ instantiated an instance of class com.su
%% No cached client session
*** ClientHello, TLSv1
...
-]]></programlisting>
+]]></screen>
<para>You should be able to determine any SSL-related configuration problem with the help of this log.</para>
</section>
</section>