content/apacheds/basic-ug/1.4.3-adding-partition.mdtext - directory-site - Git at Google

 Title: 1.4.3 - Adding your own partition
 NavPrev: 1.4.2-changing-admin-password.html
 NavprevText: 1.4.2 - Changing the admin password
 NavUp: 1.4-basic-configuration-tasks.html
 NavUpText: 1.4 - Basic configuration tasks
 NavNext: 1.4.4-configure-logging.html
 NavNextText: 1.4.4 - Configure logging
 Notice: 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.

 # 1.4.3 - Adding your own partition

 This section describes how to add your own data partition.

 [TOC]

 ## What are partitions?

 In ApacheDS entries are stored in partitions.  Each partition contains a complete entry tree, also referred to as a DIT. Multiple partitions may exist and the entry trees they contain are disconnected from each other, meaning that changes to entries in partition _A_ would never affect entries in partition _B_. The entries in a particular partition are stored below some naming context called the partition suffix.

 The default implementation of partitions is based on [JDBM](http://jdbm.sourceforge.net/) B+Trees (but it's possible to add custom partition implementations). The ApacheDS default configuration contains a a data partition with the suffix "dc=example,dc=com". The image below shows the suffixes of a freshly installed ApacheDS within Apache Directory Studio.

 ![Partition in studio after installation](images/partitions-in-studio-after-installation.png)

 The schema subsystem and ApacheDS itself store their information in special partitions, "ou=schema", "ou=config" and "ou=system" respectively.

 ## Minimal partition definition

 For the examples in the following sections, we want to add a partition with the suffix "o=sevenSeas". This requires editing of the configuration, and injecting a first entry, associated with the root of this partition (here, "o=sevenseas"). This can be done using _Apache Directory Studio_. Open the server configuration :

 ![Studio Apacheds Configuration](images/studio-apacheds-configuration1.png)

 and select the _Partitions_ tab :

 ![Studio Apacheds Partitions Configuration](images/studio-partitions-configuration.png)

 Add another jdbmPartition element for the sevenSeas partition, just below the _example_ partition:

 ![SevenSeas Partition Creation](images/sevenseas-partition-creation.png)

 As you can see, we have modified the _ID_ and the _Suffix_, all the other parameters remaining to their default values.

 Save the configuration now, and restart the server.

 The server has a new suffix now, but no context entry has been created for it. If you connect with an LDAP Browser (Apache Directory Studio for instance), the partition is only visible in the Root DSE. Below the Entry Editor of Directory Studio for the Root DSE after connecting to an ApacheDS instance configured like above.

 ![RootDSE](images/sevenseas-naming-context.png)

 Before using the partition (e.g. adding entries), you have to add a context entry. If you plan to load LDIF data to your partition anyway, simply provide the context entry (the "root" of your partition) as a first data set. In our example it might look like this:

 	dn: o=sevenSeas
 	o: sevenSeas
 	objectClass: top
 	objectClass: organization
 	description: The context entry for suffix o=sevenSeas

 It is also possible to import a file to ApacheDS which only contains such an entry, of cause. Here is an example on how to procede for the seven seas :

 In the LDAP Browser of Directory Studio, right click on the DIT entry and select "Import \-> LDIF Import...". A file selections dialog appears. Browse to the LDIF file and click Finish. The entry (or entries, if you provide more of them) will be added to to partition.

 The following image depicts the partitions after reconnecting with Apache Directory Studio (_LDAP Browser_ view).

 ![Partition in Studio after addition](images/partitions-in-studio-after-addition.png)

 ## Adding a partition programmatically

 The same o=sevenseas partition can be created through the application code using the Partition and DirectoryService API

 Here is the sample code to create a new partition o=sevenseas and its context entry programmatically

 	:::java
 	// Get the SchemaManager, we need it for this addition
 	SchemaManager schemaManager = directoryService.getSchemaManager();

 	// Create the partition
 	JdbmPartition sevenseasPartition = new JdbmPartition( schemaManager );
 	sevenseasPartition.setId("sevenseas");
 	Dn suffixDn = new Dn( schemaManager, "o=sevenseas" );
     sevenseasPartition.setSuffix( suffixDn );
 	sevenseasPartition.setCacheSize(1000);
 	sevenseasPartition.init(directoryService);
     sevenseasPartition.setPartitionPath( <a path on your disk> );

 	// Create some indices (optional)
 	sevenseasPartition.addindex( new JdbmIndex( "objectClass", false ) );
 	sevenseasPartition.addindex( new JdbmIndex( "o", false ) );

 	// Initialize the partition
 	sevenseasPartition.initialize();

 	// create the context entry
 	Entry contextEntry = new DefaultEntry( schemaManager, "o=sevenseas",
 		"objectClass: top",
 		"objectClass: organization",
 		"o: sevenseas" );

 	// add the context entry
     sevenseasPartition.add( new AddOperationContext( null, entry ) );

 	// We are done !

 ## More configuration options for a JDBM partition

 Here is a list of the used attributes, their default values and meaning :

 | Property | Description | Default Value | Required |
 |:-:|:-:|:-:|:-:|
 | ads-partitionId | Uniquely identifies the partition | N/A | yes |
 | ads-partitionSuffix | A DN ("o=sevenseas"), for instance | N/A | yes |
 | ads-contextEntry | The context entry | Will be automatically deduced if no value is provided | no |
 | ads-optimizerEnabled | Tells the server to turn on the optimizer | true | no |
 | ads-partitionCacheSize | The cache size (only for JDBM partitions) | -1 (no cache) | no |
 | ads-partitionSyncOnWrite | Syncs disks on every write operation | true | no |


 ## Adding a partition manually

 When migrating from an earlier release, or perhaps a different LDAP Directory product, you might prefer to manually add your own partition with your specific directory root DN. There are two techniques available, and the most appropriate will depend on whether you have already allowed the apacheds server to start.

 When the server starts for the first time after installation, _config.ldif_ is renamed to *config.ldif_migrated*. After that time, this priming ldif file is never referred to again, so any changes you make will be ignored. [The reason for this change is discussed in a JIRA](https://issues.apache.org/jira/browse/DIRSERVER-2050).


 ### Before starting the server

 Therefore, if you would like to have your (empty) partition created immediately following installation, you should prevent your server from starting during or after installation, i.e. when config.ldif has not yet been migrated.

 Next, edit _config.ldif_ to change all occurrences of "_example_" to suit the name of your own partition. Once the server has started and you run your first ldapsearch as the admin user, you will see that the server has created your own empty partition (instead of the example one).

 Note that the entry for the "_example_" partition does NOT have an _ads-contextEntry_ attribute. This "signature" attribute is created during the "migration" process (see below for details).

 Subsequent ldif changes to your new partition should work provided they use the default schema.


 ### With ldapmodify to a running server

 This is task more tricky because the root of your new partition MUST have a valid _ads-contextEntry_ attribute and you must determine its value. The other attributes (see the definitions above) are quite straightforward, but this control value must be synthesised based on the specific attribute values of your own partition.

 Let us look at the ldif required to add the "example" partition:

 	dn: ads-partitionId=example,ou=partitions,ads-directoryServiceId=default,ou=config
 	objectclass: top
 	objectClass: ads-base
 	objectclass: ads-partition
 	objectclass: ads-jdbmPartition
 	ads-partitionSuffix: dc=example,dc=com
 	ads-contextentry:: ZG46IGRjPWV4YW1wbGUsZGM9Y29tCmRjOiBleGFtcGxlCm9iamVjdGNsYXNzOiBkb21haW4Kb2JqZWN0Y2xhc3M6IHRvcAoK
 	ads-jdbmpartitionoptimizerenabled: TRUE
 	ads-partitioncachesize: 10000
 	ads-partitionsynconwrite: TRUE
 	ads-partitionid: example
 	ads-enabled: TRUE

 The _ads-contextentry_ attribute is a binary value which has been base64 encoded. The algorithm has to be followed accurately to be successful. Consider our example partition and take these four lines:

 	dn: dc=example,dc=com
 	dc: example
 	objectclass: domain
 	objectclass: top

 Base64 these four lines as a single string (with \n newlines, but without the prefix spaces). The result should match the _ads-contextentry_ value shown above.

 However, you need to be careful because simply adding an extra space or newline will change the base64 value and make it unacceptable to the server. Also, any valid UTF-8 attribute values which are not in the base64 character set (such as accented characters) _MUST_ be base64-encoded strings, which effectively makes them double-encoded.
 e.g. _"dn: cn=lécharny,dc=com"_ needs to be specified as _"dn:: Y249bMOpY2hhcm55LGRjPWNvbQ=="_.

 You will probably want to create some associated index entries. You can use those of the "_example_" partition in _config.ldif-migrated_ for your templates (which do not require any special encoded attributes).
	Title: 1.4.3 - Adding your own partition
	NavPrev: 1.4.2-changing-admin-password.html
	NavprevText: 1.4.2 - Changing the admin password
	NavUp: 1.4-basic-configuration-tasks.html
	NavUpText: 1.4 - Basic configuration tasks
	NavNext: 1.4.4-configure-logging.html
	NavNextText: 1.4.4 - Configure logging
	Notice: 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.

	# 1.4.3 - Adding your own partition

	This section describes how to add your own data partition.

	[TOC]

	## What are partitions?

	In ApacheDS entries are stored in partitions. Each partition contains a complete entry tree, also referred to as a DIT. Multiple partitions may exist and the entry trees they contain are disconnected from each other, meaning that changes to entries in partition _A_ would never affect entries in partition _B_. The entries in a particular partition are stored below some naming context called the partition suffix.

	The default implementation of partitions is based on [JDBM](http://jdbm.sourceforge.net/) B+Trees (but it's possible to add custom partition implementations). The ApacheDS default configuration contains a a data partition with the suffix "dc=example,dc=com". The image below shows the suffixes of a freshly installed ApacheDS within Apache Directory Studio.

	![Partition in studio after installation](images/partitions-in-studio-after-installation.png)

	The schema subsystem and ApacheDS itself store their information in special partitions, "ou=schema", "ou=config" and "ou=system" respectively.

	## Minimal partition definition

	For the examples in the following sections, we want to add a partition with the suffix "o=sevenSeas". This requires editing of the configuration, and injecting a first entry, associated with the root of this partition (here, "o=sevenseas"). This can be done using _Apache Directory Studio_. Open the server configuration :

	![Studio Apacheds Configuration](images/studio-apacheds-configuration1.png)

	and select the _Partitions_ tab :

	![Studio Apacheds Partitions Configuration](images/studio-partitions-configuration.png)

	Add another jdbmPartition element for the sevenSeas partition, just below the _example_ partition:

	![SevenSeas Partition Creation](images/sevenseas-partition-creation.png)

	As you can see, we have modified the _ID_ and the _Suffix_, all the other parameters remaining to their default values.

	Save the configuration now, and restart the server.

	The server has a new suffix now, but no context entry has been created for it. If you connect with an LDAP Browser (Apache Directory Studio for instance), the partition is only visible in the Root DSE. Below the Entry Editor of Directory Studio for the Root DSE after connecting to an ApacheDS instance configured like above.

	![RootDSE](images/sevenseas-naming-context.png)

	Before using the partition (e.g. adding entries), you have to add a context entry. If you plan to load LDIF data to your partition anyway, simply provide the context entry (the "root" of your partition) as a first data set. In our example it might look like this:

	dn: o=sevenSeas
	o: sevenSeas
	objectClass: top
	objectClass: organization
	description: The context entry for suffix o=sevenSeas

	It is also possible to import a file to ApacheDS which only contains such an entry, of cause. Here is an example on how to procede for the seven seas :

	In the LDAP Browser of Directory Studio, right click on the DIT entry and select "Import \-> LDIF Import...". A file selections dialog appears. Browse to the LDIF file and click Finish. The entry (or entries, if you provide more of them) will be added to to partition.

	The following image depicts the partitions after reconnecting with Apache Directory Studio (_LDAP Browser_ view).

	![Partition in Studio after addition](images/partitions-in-studio-after-addition.png)

	## Adding a partition programmatically

	The same o=sevenseas partition can be created through the application code using the Partition and DirectoryService API

	Here is the sample code to create a new partition o=sevenseas and its context entry programmatically

	:::java
	// Get the SchemaManager, we need it for this addition
	SchemaManager schemaManager = directoryService.getSchemaManager();

	// Create the partition
	JdbmPartition sevenseasPartition = new JdbmPartition( schemaManager );
	sevenseasPartition.setId("sevenseas");
	Dn suffixDn = new Dn( schemaManager, "o=sevenseas" );
	sevenseasPartition.setSuffix( suffixDn );
	sevenseasPartition.setCacheSize(1000);
	sevenseasPartition.init(directoryService);
	sevenseasPartition.setPartitionPath( <a path on your disk> );

	// Create some indices (optional)
	sevenseasPartition.addindex( new JdbmIndex( "objectClass", false ) );
	sevenseasPartition.addindex( new JdbmIndex( "o", false ) );

	// Initialize the partition
	sevenseasPartition.initialize();

	// create the context entry
	Entry contextEntry = new DefaultEntry( schemaManager, "o=sevenseas",
	"objectClass: top",
	"objectClass: organization",
	"o: sevenseas" );

	// add the context entry
	sevenseasPartition.add( new AddOperationContext( null, entry ) );

	// We are done !

	## More configuration options for a JDBM partition

	Here is a list of the used attributes, their default values and meaning :

	\| Property \| Description \| Default Value \| Required \|
	\|:-:\|:-:\|:-:\|:-:\|
	\| ads-partitionId \| Uniquely identifies the partition \| N/A \| yes \|
	\| ads-partitionSuffix \| A DN ("o=sevenseas"), for instance \| N/A \| yes \|
	\| ads-contextEntry \| The context entry \| Will be automatically deduced if no value is provided \| no \|
	\| ads-optimizerEnabled \| Tells the server to turn on the optimizer \| true \| no \|
	\| ads-partitionCacheSize \| The cache size (only for JDBM partitions) \| -1 (no cache) \| no \|
	\| ads-partitionSyncOnWrite \| Syncs disks on every write operation \| true \| no \|


	## Adding a partition manually

	When migrating from an earlier release, or perhaps a different LDAP Directory product, you might prefer to manually add your own partition with your specific directory root DN. There are two techniques available, and the most appropriate will depend on whether you have already allowed the apacheds server to start.

	When the server starts for the first time after installation, _config.ldif_ is renamed to config.ldif_migrated. After that time, this priming ldif file is never referred to again, so any changes you make will be ignored. [The reason for this change is discussed in a JIRA](https://issues.apache.org/jira/browse/DIRSERVER-2050).


	### Before starting the server

	Therefore, if you would like to have your (empty) partition created immediately following installation, you should prevent your server from starting during or after installation, i.e. when config.ldif has not yet been migrated.

	Next, edit _config.ldif_ to change all occurrences of "_example_" to suit the name of your own partition. Once the server has started and you run your first ldapsearch as the admin user, you will see that the server has created your own empty partition (instead of the example one).

	Note that the entry for the "_example_" partition does NOT have an _ads-contextEntry_ attribute. This "signature" attribute is created during the "migration" process (see below for details).

	Subsequent ldif changes to your new partition should work provided they use the default schema.


	### With ldapmodify to a running server

	This is task more tricky because the root of your new partition MUST have a valid _ads-contextEntry_ attribute and you must determine its value. The other attributes (see the definitions above) are quite straightforward, but this control value must be synthesised based on the specific attribute values of your own partition.

	Let us look at the ldif required to add the "example" partition:

	dn: ads-partitionId=example,ou=partitions,ads-directoryServiceId=default,ou=config
	objectclass: top
	objectClass: ads-base
	objectclass: ads-partition
	objectclass: ads-jdbmPartition
	ads-partitionSuffix: dc=example,dc=com
	ads-contextentry:: ZG46IGRjPWV4YW1wbGUsZGM9Y29tCmRjOiBleGFtcGxlCm9iamVjdGNsYXNzOiBkb21haW4Kb2JqZWN0Y2xhc3M6IHRvcAoK
	ads-jdbmpartitionoptimizerenabled: TRUE
	ads-partitioncachesize: 10000
	ads-partitionsynconwrite: TRUE
	ads-partitionid: example
	ads-enabled: TRUE

	The _ads-contextentry_ attribute is a binary value which has been base64 encoded. The algorithm has to be followed accurately to be successful. Consider our example partition and take these four lines:

	dn: dc=example,dc=com
	dc: example
	objectclass: domain
	objectclass: top

	Base64 these four lines as a single string (with \n newlines, but without the prefix spaces). The result should match the _ads-contextentry_ value shown above.

	However, you need to be careful because simply adding an extra space or newline will change the base64 value and make it unacceptable to the server. Also, any valid UTF-8 attribute values which are not in the base64 character set (such as accented characters) _MUST_ be base64-encoded strings, which effectively makes them double-encoded.
	e.g. _"dn: cn=lécharny,dc=com"_ needs to be specified as _"dn:: Y249bMOpY2hhcm55LGRjPWNvbQ=="_.

	You will probably want to create some associated index entries. You can use those of the "_example_" partition in _config.ldif-migrated_ for your templates (which do not require any special encoded attributes).