+ +	+ The first time is always the hardest! +
+	+ +We presume this is your first encounter and so many bases will be covered this +time around. Every other trail will build on this information. So expect a +little less to read as you gain +momentum. +

+Fields	+Description
+identificationTag	+Identifies the ACIItem within an +entry.
+precedence	+Determine which ACI to apply with conflicting +ACIItems.
+authenticationLevel	+User's level of trust with values of none, simple, +strong
+itemOrUserFirst	+Determines order of item permissions or user +permissions.
+userClasses	+The set of users the permissions apply +to.
+userPermissions	+Permissions on protected +items

+ +	+ Denials Overpower Grants +
+	+ +When two or more conflicting ACIItems are encountered with the same precedence +the ACIItems with denials overpower ACIItems with +grants. +

+ +	+ 18.4.2.3 Authentication Level +
+	+ +... Strong authentication of the requestor is considered to exceed a requirement +for simple or no authentication, and simple authentication exceeds a requirement +for no authentication +... +

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/grantmodtoentry.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/grantmodtoentry.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/grantmodtoentry.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/grantmodtoentry.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,11 @@ + + + + + akarasulu + + + +

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/index.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/index.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/index.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/index.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,92 @@ + + + + + akarasulu + + + +

+This is a simple guide to various ApacheDS features to help users get going. +It's be no means +extensive.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Topic	+Description
+ Building +	+How to build the directory server from the +repository.
+ Authentication +	+How to bind to the server and setup custom +authenticators.
+ Authorization +	+How to enable basic access controls and what you get without +them.
+ Subentries +and the Administrative +Model +	+What they are and how to specify their scope via +subtreeSpecifications.
+ Collective +Attributes +	+How to use collective +attributes.
+ Configuration +	+How to configure and control the +server.
+ Partitions +	+How to add new partitions besides the system +partition.
+Maven + Plugin +	+How to use the plugin to extends the +schema.

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/newuser.ldif URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/newuser.ldif?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/newuser.ldif (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/newuser.ldif Thu Jan 26 14:29:42 2006 @@ -0,0 +1,18 @@ +dn: uid=jdoe,ou=users,ou=system +cn: John Doe +sn: Doe +givenname: John +objectclass: top +objectclass: person +objectclass: organizationalPerson +objectclass: inetOrgPerson +ou: Human Resources +ou: People +l: Las Vegas +uid: jdoe +mail: jdoe@apachecon.comm +telephonenumber: +1 408 555 5555 +facsimiletelephonenumber: +1 408 555 5556 +roomnumber: 4613 +userpassword: test + Added: directory/trunks/apacheds/site/src/site/xdoc/users/partitions.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/partitions.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/partitions.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/partitions.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,157 @@ + + + + + akarasulu + + + +

+Partitions are entry stores assigned to a naming context. The idea behind a +partition is that it stores a subset of the Directory Information Base (DIB). +Partitions can be implemented in any way so long as they adhere to +interfaces.

+ +

+Presently the server has a single partition implementation. This implementation +is used for both the system partition and user partitions. It +uses + JDBM +as the underlying B+Tree implementation for storing +entries. +

+Other implementations are possible like in memory based partitions either BTree +based or based on something +like + Prevayler +. +

+Partitions have simple interfaces that can be used to align any data source to +the LDAP data model thereby accessing it via JNDI or via LDAP over the wire. +This makes the server very flexible as a bridge to standardize access to +disparate data sources and formats. Dynamic mapping based backends are also +interesting.

+ + +

+The system partition is a very special partition that is hardcoded to hang off +of the *ou=system* naming context. It is always present and contains +administrative and operational informations needed by the server to operate. +Hence its +name.

+The server's subsystems will use this partition to store informations critical +to its +operation.

+ + +

+Several partitions can be assigned to different naming contexts within the +server so long as their names do not overlap such that one partition's naming +context is contained within another's. The root nexus is a fake partition that +does not really store entries. It maps other entry storing partitions to naming +contexts and routes backing store calls to the partition containing the entry +associated with the +operation.

+ + +

+User partitions are partitions added by users. When you download and start using +the server you may want to create a separate partition to store the entries of +your application. To us user (sometimes also referred to as application) +partitions are those that are not the system partition! In the following section +we describe how a user partition can be created in the +server.

+ +

+Adding new application partitions to the server is a matter of adding +DirectoryPartitionConfiguration objects to the StartupConfigration added to the +JNDI environment. These properties are used in both standalone and in embedded +configurations. You'll see how to configure partitions by example using xml +configuration files with the standalone application and programatically for +embedding.

+Until this section is filled with more specific examples just geared towards the +configuration of partitions please +see + Configuration +. +

+Things we'd like to do with the existing partitioning scheme and +beyond.

+ +

+Today we have some limitations to the way we can partition the DIB. Namely we +can't have a partition within a partition and sometimes this makes sense. +Eventually we intend to enable this kind of functionality using a special type +of nexus which is both a router and a backing store for entries. It's smart +enough to know what to route verses when to use its own database. Here's +a + JIRA improvement +specifically aimed at achieving this +goal. +

+ + +

+Obviously we want as many different kinds of partitions as possible. Some really +cool ideas have floated around out there for a while. Here's a list of +theoretically possible partition types that might be useful or just +cool:

+Partitions that use JDBC to store entries. These would probably be way too slow. +However they might be useful if some mapping were to be used to represent an +existing application's database schema as an LDAP DIT. This would allow us to +expose any database data via LDAP. Great for +virtualization.
+Partitions using other LDAP servers to store their entries. Why do this when +introducing latency? Perhaps you want to proxy other servers or make other +servers behave like the personality of another server all +together.
+A partition that serves out the Windows registry via LDAP. A standard mechanism +to map the Windows registry to an LDAP DIT is pretty simple. This would be a +neat way to expose client machine registry +management.
+A partition based on an in-memory BTree implementation. This would be fast and +really cool for storing things like schema info. It would also be cool for +staging data between memory and +disk.
+A partition based +on + Prevayler +. This is like an in-memory partition but you can save it at the end of the day. +This might be really useful especially for things the system partition which +almost always need to be in memory. The system partition can do this by using +really large caches equal to the number of entries in the system +partition. +

+ + +

+Other aspirations include entry partitioning within a container context. Imagine +having 250 million entries under '*ou=citizens,dc=census,dc=gov*'. You don't +want all 250 million in one partition but would like to subpartition these +entries under the same context based on some attribute. Basically we will be +using the attribute's value to implement subpartitioning where within a single +context we are partitioning entries. The value is used to hash entries across +buckets (the buckets are other partitions). Yes, this is a bit on the heavy duty +end but it would be useful in several +situations.

+ +

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/plugin.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/plugin.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/plugin.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/plugin.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,267 @@ + + + + + akarasulu + + + +

+Currently the primary function of the plugin is to generate server class files +for OpenLDAP schemas. These class files contain hard coded schema objects +representing those found in the OpenLDAP files. Why bother you may ask? There +are a few reasons for +this:

+Compiled hard coded files load into the server really fast in +theory.
+Published schemas never really change so why do they need to be in a human +readable +form?
+Eventually, schema changes made through LDAP will be preserved through +restarts.
+Extra code generation phase is not that hard with a plugin +tool.
+Schema verification can occur before deploying schemas into the +server.
+This was really easy for now but if people don't like it we can change +it.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +

+Property	+Optional?	+Description
+maven.ldap.server.schema.target.dir	+Yes	+Default value is +target/schema
+maven.ldap.server.schema.ownerDefault	+Yes	+Default value is +uid=admin,ou=system.
+maven.ldap.server.schema.dir	+Yes	+Default value is +src/schema.
+maven.ldap.server.schema.packageDefault	+Yes	+Default value is +org.apache.ldap.server.schema.bootstrap.

+ + + + + + + + + + + + + + + + + + + + + + + +

+Goal	+Description
+directory:generate	+Generates class files for OpenLDAP +schemas.
+directory:init	+Finds the required parameters needed for the goals of the +plugin.
+directory:prepare-filesystem	+Creates source output directories used to deposite schema files that are +generated.
+directory:schema	+Top level schema generating function that uses other goals to coordinate +generation.

+Take a look at how we integrate this into the directory server +build + here +. +

+ +

+You want to use the plugin to generate classes for your own schema. Here's a +step wise process you can follow to do that using +maven:

+Place your schema files (i.e. *foo.schema*) with the schema extension into +$\{basedir\}/src/main/schema. If you opt to store it in another location you +must override the maven.ldap.server.schema.dir property in your +project.properties file. For each schema file add the file base name to the +maven.ldap.server.schemas property which is a space separated +list.
+The plugin will by default generate java files within the +$\{basedir\}/target/schema directory. If you would like to generate code +elsewhere you must override the maven.ldap.server.schema.target.dir property in +your project.properties +file.
+By default the plugin generates code in a server schema package: +org.apache.ldap.server.schema.bootstrap. If you want generated code for a schema +to be put into a package other than this, then you're going to need to set the +package property for the schema. The package property key is composed of the +following base, maven.ldap.server.schema.package. with the name of the schema +(without the extension) appended to it. So for schema file foo.schema the +following property key would be used: maven.ldap.server.schema.package.foo where +foo is the schema +name.
+Using the same pattern above for all schema specific properties you can set +other per schema properties as well. One of these properties is the dependency +list for a schema. Schemas can obviously depend on others. The schema dependency +list is a comma separated list of other schema names. These schemas need not be +present in your project to generate the code for your schema. The dependent +schema classes must however be present within the server at start up time in +order to load and use your schema. At the end we list the default schemas +already packaged into the server's jar. You can use any one of these schemas as +dependencies needed by your schema and not worry about their presence. The +property key base for the schema dependency list is +maven.ldap.server.schema.deps. and for a foo.schema file the full key would be +maven.ldap.server.schema.deps.foo
+Each schema has an owner associated with it. If you want the owner to be +anything other than the server's super user you may want to set the owner +property for the schema in your project.properties file. The property key base +for the schema is maven.ldap.server.schema.owner. so don't forget to append the +schema name to +it.

+Once setup you can invoke maven to generate the schema sources like +so:

+ [akarasulu@newton dib]$ maven directory:schema + __ __ +| \/ |__ _Apache__ ___ +| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~ +|_| |_\__,_|\_/\___|_||_| v. 1.0.2 + +Attempting to download ldap-common-0.8.0-SNAPSHOT.jar. +Attempting to download apacheds-shared-0.8.0-SNAPSHOT.jar. +Attempting to download apacheds-protocol-0.8.0-SNAPSHOT.jar. +Attempting to download snickers-codec-0.2.0-SNAPSHOT.jar. +Attempting to download ldap-snickers-provider-0.8.0-SNAPSHOT.jar. +Attempting to download snickers-ber-0.2.0-SNAPSHOT.jar. +Attempting to download seda-0.2.0-SNAPSHOT.jar. +Attempting to download maven-directory-plugin-0.8.0-SNAPSHOT.jar. +Attempting to download ldap-common-0.8.0-SNAPSHOT.jar. +Attempting to download apacheds-shared-0.8.0-SNAPSHOT.jar. +build:start: + +directory:schema: +directory:init: + +directory:prepare-filesystem: + +directory:generate: + [echo] Generated schema producer classes for autofs.schema + [echo] Generated schema producer classes for core.schema + [echo] Generated schema producer classes for cosine.schema + [echo] Generated schema producer classes for corba.schema + [echo] Generated schema producer classes for eve.schema + [echo] Generated schema producer classes for inetorgperson.schema + [echo] Generated schema producer classes for java.schema + [echo] Generated schema producer classes for krb5kdc.schema + [echo] Generated schema producer classes for nis.schema + [echo] Generated schema producer classes for system.schema + [echo] Generated schema producer classes for scheduleworld.schema + [touch] Creating /home/akarasulu/projects/directory/server/trunk/core/target/schema/.flagfile +BUILD SUCCESSFUL +Total time: 28 seconds +Finished at: Tue Dec 14 15:26:26 EST 2004 + +

+The example above is from the server's core project. If you would like to look +at how to use this plugin best the server +core + project.properties +file here is perhaps the best place to look. Also from the output above you can +see the schema files that are used and packaged into the server by default. This +may however change in the future to restrict the +set. +

+WARNING: As a last bit of advice make note that the plugin may be sensitive to +case for keywords in the OpenLDAP file. For example the prefix before an +objectClass or an attributeType must be in all lowercase. However words like +MUST, and MAY and SUP should all be in uppercase. So if plugin bombs just check +out where this happens and play with the case. Another thing to watch out for is +the order of terms. This we follow the RFC for which is pretty much the same as +the OpenLDAP format minus the objectclass and attributetype prefixes to the +descriptions. We figure the OpenLDAP parser is less complex if the prefixes are +there (where the parser is told if the description is an objectclass or +attributetype and does not have to figure this out). However I have encountered +schemas whose formats do not comply with standards in with respect to the order +of description fields and had to edit the files. This issue did not occur when +the files were from the OpenLDAP Foundation which means they do it right but +overlook schema objects that are not correctly +formated.

+Compile triggers and install them into the +server.
+Compile and load stored +procedures.
+Test stored procedures and +triggers.
+Generate JNDI Object and State factories from +schemas.

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/subentries.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/subentries.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/subentries.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/subentries.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,514 @@ + + + + + akarasulu + + + +

+Subentries are used for managing the administration of different aspects of the +directory. LDAP has just recently formalized the notion of subentires +in + RFC 3672 +. Subentries have existed within X.500 Directories for years with clear +specifications for administering collective attributes, schema, and access +controls. With the exception of managing collective attributes LDAP has no +equivalent *yet* for administering these aspects. However with RFC 3672, LDAP +is on its way towards adopting and adapting these mechanisms from X.500 +Directories. It is only a matter of +time. +

+For this reason we intend to remain ahead of the curve by implementing these +aspects of administration using Subentries and Administrative Areas similar to +X.500 +Directories.

+To explain this properly we're going to need to discuss a couple other things +like administrative areas (AA) and administrative points (AP) within the +directory. However for the impatient here's a quick attempt to describe what +subentries +are:

+Subentries are hidden leaf entries (which cannot have children). These entries +immediately subordinate to an administrative point (AP) within the directory. +They are used to specify administrative information for a part of the Directory +Information Tree (DIT). Subentries can contain administrative information for +aspects of access control, schema administration, and collective attributes (and +others which have not been defined in any specification +yet).

+First some definitions as provided by +X.501:

+11.1.1 administrative area: A subtree of the DIT considered from the perspective +of +administration.
+11.1.2 administrative entry: An entry located at an administrative +point.
+11.1.3 administrative point: The root vertex of an administrative +area.
+11.1.5 autonomous administrative area: A subtree of the DIT whose entries are +all administered by the same Administrative Authority. Autonomous administrative +areas are +non-overlapping.
+11.1.11 inner administrative area: A specific administrative area whose scope is +wholly contained within the scope of another specific administrative area of the +same +type.
+11.1.17 specific administrative area: A subset (in the form of a subtree) of an +autonomous administrative area defined for a particular aspect of +administration: access control, subschema or entry collection administration. +When defined, specific administrative areas of a particular kind partition an +autonomous administrative +area.
+11.1.18 specific administrative point: The root vertex of a specific +administrative +area.

+Now take a step back because the above definitions are, well, from a sleep +inducing spec. Let's just talk about some +situations.

+Presume you're the uber directory administrator over at WallyWorld (a Walmart +competitor). Let's say WallyWorld uses their corporate directory for various +things including their product catalog. As the uber admin you're going to have a +bunch of people wanting access, update and even administer your directory. +Entire departments within WallyWorld are going to want to control different +parts of the directory. Sales may want to manage the product catalog, while +operations may want to manage information in other areas dealing with suppliers +and store locations. Whatever the domain some department will need to manage the +information as the +authority.

+Each department will probably designate different people to manage different +aspects of their domain. You're not going to want to deal with their little +fiefdoms instead you can delegate the administration of access control policy to +a departmental contact. You will want to empower your users and administrative +contacts in these departments so they can do part of the job for you. Plus it's +much better than having to communicate with everyone in the company to meet +their needs. This is where the delegation of authority comes into the +picture.

+Usually administrators do this already to an extent without defining +administrative areas. Giving users the ability to change their own passwords for +example is a form of delegation. This is generally a good idea because you don't +want to set passwords for people. First because you don't want to see the +password and secondly because of the management nightmare you'd have to deal +with. Expand this idea out a little further and think about delegating +administration not of users on their passwords but of entire subtrees in the +directory to administrative contacts in various +departments.

+Do you really want to manage the corporate product catalog or just let the sales +department manage it? But what do we mean by manage? You want sales people to +create, and delete entries but they may only trust a few people to do this. +Others may just view the catelog. Who are the people with add/remove powers and +why should you have to be involved with deciding this ever changing departmental +policy? Instead you can delegate the management of access controls in this area +to a administrative contact in the sales department. The sales contact can then +administer access controls for their department. They're closer to the people in +sales than you are and they probably have more bandwidth to handle sales related +needs than you do. Delegating authority in this fashion is what X.500 engineers +pioneered in the early 80's with the telecom boom in Europe. They knew different +authorities will want to manage different aspects of directory administration +for themselves. These X.500 definitions are there to be able to talk about +administrative areas within the directory. Now let's get back to what these +things are +exactly.

+An administrative area is some part of the directory tree that is arbitrarily +defined. The tree can be split into different administrative areas to delegate +authority for managing various aspects of administration. For example you can +have a partition hanging off of *'dc=example,dc=com'* with an *'ou=product +catalog'* area. You may want this area to be managed by the sales department +with respect to the content, schema, it's visibility, and collective attributes. +Perhaps you only want to delegate only one aspect of administration , access +control, since you don't want people messing around with schema. To do so you +can define everything under *'ou=product catalog'* to be an administrative area +specifically for access control and delegate that aspect only. In that case the +entry, *'ou=product catalog,dc=example,dc=com'* becomes an administrative entry. +It is also the administrative point for the area which is the tree rooted at +this +entry.

+Not all administrative areas are equal. There are really two kinds : +*autonomous* and *inner* areas. Autonomous areas are areas of administration +that cannot overlap. Meaning someone is assigned as the supreme authority for +that subtree. Inner areas are, as their name suggests, nested administrative +areas within autonomous areas and other inner areas. Yes, you can nest these +inner areas as deep as you like. You may be asking yourself what the point to +all this is. Well, say you're the supreme admin of admins. You delegate the +authority to manage access control for the corporate catalog to the sales admin. +That admin may in turn decide to delegate yet another area of the catalog to +another contact within a different department. You delegate access control +management to the sales admin over the product catalog. The sales admin realizes +that the job is way bigger than he can manage so he delegates administration of +subtrees in the catalog to various contacts in different departments. For +example regions of the catalog under *'ou=electronics' and 'ou=produce'* may be +delegated to different contacts in their respective departments. However the +sales admin still reserves the ability to override access controls in the +catalog. The sales admin can change who manages access controls for different +parts of the catalog. This chain of delegation is possible using inner +administrative +areas.

+Usually an entry is selected as the administrative point and marked with an +operational attribute. The attributeType of the operational attribute is +'administrativeRole'. This attribute can have the following +values:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+OID	+NAME
+2.5.23.1	+autonomousArea
+2.5.23.2	+accessControlSpecificArea
+2.5.23.3	+accessControlInnerArea
+2.5.23.4	+subschemaAdminSpecificArea
+2.5.23.5	+collectiveAttributeSpecificArea
+2.5.23.6	+collectiveAttributeInnerArea

+As you can see, 3 aspects, *schema*, *collective attributes*, and *access +control* are considered. An autonomous administrative area can hence be +considered with respect to all three specific aspect of administration. If an AP +is marked as an autonomousArea it generally means that administration of all +aspects are allowed by the authority. If marked with a specific aspect then only +that aspect of administration is delegated. The administrativeRole operational +attribute is multivalued so the uber admin can delegate any number of specific +administration aspects as he +likes.

+Also notice that two aspects, collective attribute and access controls, allow +administrative points to be inner areas. Delegated authorities for these two +aspects can create inner administrative areas to further delegate their +administrative powers. The schema aspect unlike the others cannot have inner +areas because of potential conflicts this may cause which would lead to data +integrity issues. For this reason only the authority of an automomous area can +manage schema for the entire +subtree.

+An autonomous administrative area (AAA) includes the AP and spans all +descendants below the AP down to the leaf entries of the subtree with one +exception. If another AAA, let's call it AAA' (prime) is present and rooted +below the first AAA then the first AAA does not include the entries of AAA'. +Translation: an AAA spans down until other AAAs or leaf entries are encountered +within the subtree. This is due to the fact that AAAs do not overlap as do inner +AAs +(IAA).

+Subentries hold administrative information for an IAA or an AAA. These entries +are of the objectClass 'subentry'. The subentry must contain two attributes: a +*commonName* and a *subtreeSpecification*. The commonName (or cn) is used as the +subentry's rdn attribute. The subtreeSpecification describes the collection of +entries within the AA (IAA or AAA) that the administrative instruction applies +to.

+A subtree specification uses various parameters described below to define the +set of entries. Note that entries need not exist for them to be included in the +collection on +addition.

+ +

+This is the relative name of the root vertex of the subtree relative to the AP. +So if the AP is *'ou=system'* and the base is *'ou=users'*, the subtree begins +at *'ou=users,ou=system'*. The base can be any length of name components +including 0 where it's the empty name "". In this case, the subtree begins at +the AP, *'ou=system'* in the example +above.

+ + +

+Chop specification parameters define specific nodes to be excluded from the +collection as well as how deep the subtree spans and even where it starts +relative to the +base.

+ +

+These parameters are names relative to the root vertex of the subtree, hence +they are relative to the base parameter. They specify whether or not an entry +and its descendants are to be excluded from the +collection.

+When *chopBefore* is used, the entry specified is excluded from the collection. +When *chopAfter* is used the entry is included however all descendants below the +entry are +excluded.

+ + +

+The minimum parameter describes the minimum DN length required to include +entries within the selection. The maximum parameter describes the maximum DN +length allowed before entries are excluded from the +collection.

+ + + +

+The specification filter is a unique beast. It's a filter like a search filter, +however its syntax and expressivity is radically different. Think of a +specification filter as a simplified form of search filters where all terms only +test the objectClass attribute and only equality checks can be performed. Oh and +yes, you do have logical operators like *and*, *or* and +*not*.

+So with a filter you have the ability to "refine" the subtree already specified +with chop, and base parameters. This "refinement" makes it so the collection is +not really a contiguous subtree of entries but a possibly disconnected set of +selected based on the objectClass characteristics of entries. This feature of a +subtreeSpecification is very powerful. For example, I can define a subtree to +cover a region of an AA yet include only inetOrgPersons within this +region.

+ + +

+Different subentry objectClasses exist for applying different aspects of +administration to the entry collection described by their subtreeSpecification +attribute. By the way the subtreeSpecification attribute is single valued so +there can only be one in a subentry. However you can have several subentries of +various kinds under an AP. Furthermore their collections can +intersect.

+The kinds of subentries allowed though are limited by the administrativeRole of +the AP. If the AP is for an access control AA then you can't add a subentry to +it for schema administration. The AP must have the role for schema +administration as well to allow both types of +subentries.

+ApacheDS does not manage schema using subentries in the formal X.500 sense right +now. There is a single global subentry defined at *'cn=schema'* for the entire +DSA. The schema is static and cannot be updated at runtime even by the +administrator. Pretty rough for now but it's the only lagging subsystem. We'll +of course make sure this subsystem catches +up.

+ApacheDS does however manage collective attributes using subentries. An AP that +takes the administrativeRole for managing collective attributes can have +subentries added. These subentries are described in greater detail +here: + Collective +. In short, collective attributes added to subentries show up within entries +included by the subtreeSpecification. Adding, removing, and modifying the values +of collective attributes within the subentries instantly manifest changes in the +entries selected by the subtreeSpecification. Again +consult + Collective +for a hands on explanation of how to use this +feature. +

+ApacheDS performs access control and allows delegation using subentries, AAAs, +and IAAs. ApacheDS uses the Basic Access Control Scheme from X.501 to manage +access control. By default this subsystem is deactivated because it locks down +everything except access by the admin. More information about hands on use is +available +here: + Authorization +. However to summarize its association with subentries, access control +information (ACI) can be added to subentries under an AP for access control AAs. +When one or more ACI are added in this fashion, the access rules of the ACI set +apply to all entries selected by the subtreeSpecification. Even with this +powerful feature individual entries can have ACI added to them for controlling +access to them. Also there are things you can do with ACI added to subentries +that cannot be done with entry level ACI. For example you cannot allow entry +addition with entry ACI. You must use subtreeSpecifications to define where +entries may be added because those entries and their parents may not exist +yet. +

+ + +

+The best way to demonstrate subtreeSpecification values are through examples. +Here's the simplest filter of them +all:

+ {} + +

+This basically selects the entire contiguous subtree below the AP. The base is +the empty name and it's rooted at the +AP.

+Next step let's add a +base:

+ { base "ou=users" } + +

+If this is the subtreeSpecification under the AP, *'ou=system'*, then it selects +every entry under +*'ou=users,ou=system'*.

+OK that was easy so now let's slice and dice the tree now using the minimum and +maximum chop +parameters.

+ { minimum 3, maximum 5 } + +

+This selects all entries below *'ou=system'* which have a DN size equal to 3 +name components, but no more than 5. So for example +*'uid=jdoe,ou=users,ou=system'* would be included but +*'uid=jack,ou=do,ou=not,ou=select,ou=users,ou=system'* would not be included. +Let's continue and combine the base with just a minimum +parameter:

+ { base "ou=users", minimum 4 } + +

+Here the subtree starts at *'ou=users,ou=system'* if the subentry subordinates +to the AP at *'ou=system'*. The user +*'uid=jdoe,ou=deepenough,ou=users,ou=system'* is selected by the spec where as +*'uid=jbean,ou=users,ou=system'* is +not.

+It's time to add some chop +exclusions:

+ { + base "ou=users", + minimum 4, + specificExclusions { chopBefore: "ou=untrusted" } +} + +

+Again if placed at the AP *'ou=system'* this subtree would begin at +*'ou=users,ou=system'*. It would not include users that subordinate to it though +because of the minimum constraint since these users would have 3 components in +their DN. The specific exclusions prevent *'ou=untrusted,ou=users,ou=system'* +and all its descendants from being included in the collection. However +*'uid=jbean,ou=trusted,ou=users,ou=system'* would be included since it meets the +minimum requirement, is a descendant of *'ou=users,ou=system'* and is not under +the excluded DN, +*'ou=untrusted,ou=users,ou=system'*.

+Note that you can add as many exclusions as you like by comma delimiting them. +For +example:

+ { + base "ou=users", + minimum 4, + specificExclusions { chopBefore: "ou=untrusted", chopAfter: "ou=ugly", chopBefore: "ou=bad" } +} + +

+The final example includes a refinement. Again any combination of chop, filter +and base parameters can be used. The following refinement makes sure the users +selected are of the objectClass inetOrgPerson and specialUser where the OID for +the specialUser class is 32.5.2.1 +(fictitious).

+ { + base "ou=users", + minimum 4, + specificExclusions { chopBefore: "ou=untrusted", chopAfter: "ou=ugly", chopBefore: "ou=bad" } + specificationFilter and:{ item:32.5.2.1, item:inetOrgPerson } +} + +

+If you'd like to see the whole specification of the grammar used for the +subtreeSpecification take a look at Appendix A +in + RFC 3672 +. +

+ +

+In the immediate future we intend to +introduce + Triggers +, stored procedures and views into ApacheDS. Subentries will play a critical +role in the administration and application of these features. For example a +Trigger specification need not include information on what entries it applies to +since the subtreeSpecification handles this. The question of "on what" a trigger +applies to is nicely disassociated from the "which operation" part of the +specification. This makes for much better reuse of triggers. It also allows for +the pin point application of triggers to entries in the DIT. Likewise a view +itself will be defined by a specification. A view for example in a subentry can +define a region of the tree that does not exist but is shadowed from another +region all together. The possibilities here are +limitless. +

+Of course we will revamp the schema subsystem of ApacheDS to use subentries in +AAA to manage the schema in effect within different regions of the DIT. Today +most LDAP servers just have a global scheme in effect for the entire DIT served +by a DSA. We don't think that is reasonable at all. So expect some serious +advances in the design of a new schema subsystem based on +subentries.

+Replication is yet another excellent candidate for using subentries. Replication +of specific collections of entries can be managed for each cluster rather than +replicating the entire DIT served by a DSA to replicas. This way we don't only +control what is replicated but we can also control how and where it is +replicated.

+ApacheDS has implemented subentries for the administration of various aspects of +the directory and gains several powerful features as a result: namely precision +application of control to entry collections and the ability to delegate +administrative authority. For details on the administration of each aspect using +subentries +( + Collective +and + Authorization +) please see the respective +documentation. +

+As ApacheDS progresses it will gain an immense advantage from subentries. Both +for existing LDAP features like scheme and for new experimental features like +triggers, and +replication.

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/subtreespecificationgrammar.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/subtreespecificationgrammar.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/subtreespecificationgrammar.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/subtreespecificationgrammar.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,54 @@ + + + + + elecharny + + + +

+Here is the LL(1) grammar used to decode a subtreeSpecification as described +by + RFC 3672 +

+ <SubtreeSpecification> ::= '{' <spse> <base-e> <chopSpecification> <spse> <refinement-e> '}' + +<base-e> ::= + Â¬Â´baseÂ¬Âª <sps> <localName> <spse> ',' <spse> | + e + +<chopSpecification> ::= Â¬Â´chopSpecificationÂ¬Âª '{' <spse> <chopSpecification-in> '}' + +<chopSpecification-in> ::= + Â¬Â´specificExclusionsÂ¬Âª <spse> <chop-set-of-choice> <spse> <specificExclusions-follower> | + Â¬Â´minimumÂ¬Âª <sps> <number> <spse> <minimum-follower> | + Â¬Â´maximumÂ¬Âª <sps> <number> <spse> + +<specificExclusions-follower> ::= + ',' <spse> Â¬Â´minimumÂ¬Âª <sps> <number> <spse> <minimum-follower> | + ',' <spse> Â¬Â´maximumÂ¬Âª <sps> <number> <spse> + +<minimum-follower> ::= ',' <spse> Â¬Â´maximumÂ¬Âª <sps> <number> <spse> + +<refinement-e> ::= + Â¬Â´specificationFilterÂ¬Âª <sps> <refinement> | + e + +<refinement> ::= + Â¬Â´itemÂ¬Âª <spse> ':' <spse> OID <spse> | + Â¬Â´andÂ¬Âª <spse> ':' <spse> <set-of-refinement> | + Â¬Â´orÂ¬Âª <spse> ':' <spse> <set-of-refinement> | + Â¬Â´notÂ¬Âª <spse> ':' <spse> <refinement> | + +<set-of-refinement> ::= '{' <spse> <refinement> <refinements> '}' <spse> + +<refinements> ::= + ',' <spse> <refinement> | + e + +<localName> ::= '"' DN '"' + +

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/userclasses.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/userclasses.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/userclasses.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/userclasses.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,166 @@ + + + + + akarasulu + + + +

+A large part of managing access control information involves the specification +of *who* can perform *which* operation on *what* protected resource (entries, +attributes, values etc). At evaluation time a requestor of an operation is +known. The identity of the requestor is checked to see if it falls into the set +of users authorized to perform the operation. User classes are hence definitions +of a set of zero or more users permissions apply to. Several constructs exist +for specifying a user +class.

+There are 3 really simple constructs for specifying the user. These constructs +are listed in the table +below:

+ + + + + + + + + + + + + + + + + + + + + +

+User Class +Construct	+Meaning	+Example
+allUsers	+Any user with possible requirements for +AuthenticationLevel	+allUsers
+thisEntry	+The user with the same DN as the entry being +accessed	+thisEntry
+name	+The user with the specified +DN	+name \{ "uid=admin,ou=system" +\}

+These are pretty intuitive. Two other user classes may be a bit less easy to +understand or may require some explanation. For these we discuss them in the +sections +below.

+The *userGroup* user class construct is also pretty intuitive. It does however +require some background information about how group membership is determined for +this +purpose.

+ApacheDS associates users within a group using the *groupOfNames* and +*groupOfUniqueNames* objectClasses. To define groups an entry of either of these +objectClasses is added anywhere in the server's DIT. *member* or *uniqueMember* +attributes whose values are the DN of user entries are present within the entry +to represent membership within the +group.

+ + + + + +

+Although such group entries can be added anywhere within the DIT to be +recognized by the Authorization subsystem, a recommended convention exists. Use +the 'ou=groups' container under a namingContext/partition within the server to +localize groups. Most of the time group information can be stored under +'ou=groups,ou=system'.

+Just like the *name* construct, the *userGroup* construct takes a single +parameter: the DN of the group entry. During ACI evaluation ApacheDS checks to +see if the requestor's DN is contained within the group. Below is a section from +X.501 specification which explains just how this is +done:

+In order to determine whether the requestor is a member of a userGroup user +class, the following criteria +apply:

+Here the user class specification construct is a subtree specification without a +refinement filter. Such a specification is simple yet very powerful. The subtree +defines a collection of entries. During ACI evaluation, ApacheDS will check to +see if the requestor's DN is included by this +collection.

+For more information on how to define a subtreeSpecification please +see + Subentries +and the Administrative +Model. +

+ + + + + +

+ +	+ +For this purpose a subtree is not refined. Meaning it does not evaluate +refinement filters. This is to restrict the information needed to make a +determination to just the DN of the requestor and not the entry of the +requestor. +

+The same userClass mechanism can be specified more than once if it makes sense. +There is no reason to specify allUsers more than once. More than one type of +user class mechanism can be used as well. Again some combinations just will not +make sense like having a name based userClass then allUsers. The following +ACIItem grants delete abilities to a set of users using more than one machanism. +It allows jbean, jdoe, all users in the Administrators group to delete entries. +It also allows requestors to delete their own user +entry.

+ { identificationTag "deleteAci" + precedence 255, + authenticationLevel simple, + itemOrUserFirst userFirst: + { + userClasses + { + thisEntry, + name { "uid=jbean,ou=users,ou=system" }, + name { "uid=jdoe,ou=users,ou=system" }, + userGroup { "cn=Administrators,ou=groups,ou=system" } + }, + userPermissions { { protectedItems {entry}, grantsAndDenials { grantRemove } } } + } +} + +

+ + Added: directory/trunks/apacheds/site/src/site/xdoc/users/userpermissions.xml URL: http://svn.apache.org/viewcvs/directory/trunks/apacheds/site/src/site/xdoc/users/userpermissions.xml?rev=372635&view=auto ============================================================================== --- directory/trunks/apacheds/site/src/site/xdoc/users/userpermissions.xml (added) +++ directory/trunks/apacheds/site/src/site/xdoc/users/userpermissions.xml Thu Jan 26 14:29:42 2006 @@ -0,0 +1,11 @@ + + + + + akarasulu + + + +

+ +