Package com.isode.dsapi.config

Class DSASetup

java.lang.Object
com.isode.dsapi.config.DSASetup
public class DSASetup extends Object
DSASetup. Class that handles DSA creation, DSA startup/shutdown and DSA initialisation from a template and LDIF/GAC files.

Design of DSA Creation Templates

A template is effectively a snapshot of ACI and certain DIT entries which is then transformed by user customisation and other processing to the set of data which is actually loaded up into the new DSA.

Here is a high-level flowchart of the processing: 

      (1)          (2)         (3)         (4)          (5)          (6)
   Templated -> Relocate  -> Fill in -> Fill in   -> Strip out -> Create DSA
   config/      subtrees,    missing    passwords    deselected
   snapshot     rename       entries                 rules and
                entries                              groups

(1): The config consists of an XML file plus an LDIF dump and a GAC dump.

(2): The most important stage of processing is the relocation step. The DN parameters filled in by the user are used to decide how to rearrange the DIT. Whole subtrees are moved, not just entries, and in the case of the GAC data, the handling is slightly special in that when a subtree is moved out of a parent area, the gap it leaves behind takes on the default ACI at that level (as determined by parents) instead of turning into a 'black hole'. This gives the intuitive behaviour in most cases.

DN relocation is also used for modifying the DSA DN and the users and groups -- this has the side-effect of also moving ACI and admin points or naming contexts along with the DNs which are renamed or relocated, which keeps things consistent. DN relocation is performed on all DN data, including DNs within ACI rules and within DN-value attributes in the DIT.

Note that where DN-relocation involves renaming an entry, if the RDN attribute type changes, then the load will most likely fail if there is a corresponding entry in the LDIF. For example renaming cn=test to o=test will not work when there are no 'organization' objectclass in the entry. Renaming from cn=test to cn=other is no problem, even if there is a corresponding entry, as the CN attribute will be fixed up and there are no objectclass changes required.

For this reason, to make the templates as flexible as possible, it is probably best to omit most of the entries making up the structure of the DIT, and to let DSASetup create these automatically in (3).

However, there is no problem in the case of renaming an entry which does not actually exist in the LDIF. This is because those entries are generated automatically by the third stage of the processing, and objectclasses are inserted automatically according to the final RDN attribute type.

[ NOTE: relocation doesn't work well when two subtrees are relocated to the exact same target DN -- the second one's ACI overwrites the first. Also, relocation doesn't work well when a subtree is relocated superior to some other subtree whose ACI must be kept -- the subtree's ACI will be overwritten, unless it itself is also marked as a subtree to relocate, in which case it will be preserved. In realistic cases these situations should be unlikely to occur, however. ]

(3): Where there is a gap in the tree between root and an entry which must be added or updated, or a gap within the tree between two entries, new entries are automatically created with suitable objectclasses corresponding to the RDN of the entry. (The exception to this is when the missing entries are immediately superior to a naming context, in which case they are left as glue.) This allows the tree to be manipulated freely by the user's configuration, and DSASetup makes the configuration work by inserting entries as necessary.

(4): Using predefined passwords is not secure, so for those entries that require passwords, their DNs should be added as [pw-param] tags. DSASetup will then generate a password and insert it into the entry before it is written, replacing any existing password in the LDIF.

(5): Some rules (identified by the precedence number) and some groups (identified by the DN) can be marked as optional in the template and can be deselected by the user. These rules and groups should be present in the GAC and LDIF data, but if they are deselected then they are stripped out before DSA creation. This means that DSASetup doesn't have to do any complicated operations, it just has to cleanly remove all trace of the deselected rules and groups. This allows quite complicated templates to be created.

(6): The DSA is loaded with data after all these transformations have already been done. GDAMs are created and filled as necessary, admin points set up, global access control is loaded. Because this is done right at the end, it means that we have the flexibility to make transformations within the processing stages (1-4) that would be impossible to do on a live DSA.

Since:
15.0

  • Field Details

    • DEFAULT_WINDOWS_GRACE_PERIOD

      public static final int DEFAULT_WINDOWS_GRACE_PERIOD
      Number of seconds to wait on Windows for the DSA to shutdown when we're trying to delete its directory.
      See Also:

    • MVC_TEMPLATE_DIR

      public static final String MVC_TEMPLATE_DIR
      Directory where MVault templates are stored
      See Also:

    • MHS_TEMPLATE_DIR

      public static final String MHS_TEMPLATE_DIR
      Directory where MConsole templates are stored
      See Also:

    • SLS_TEMPLATE_DIR

      public static final String SLS_TEMPLATE_DIR
      Directory where SLS related templates are stored
      See Also:

    • dispAuthData

      public static final PeerAuthData dispAuthData
      Default DISP authentication data.

  • Constructor Details

    • DSASetup

      public DSASetup()

  • Method Details

    • createFromTemplate

      public static List<BindProfile> createFromTemplate(DSACreationTemplate ct) throws IOException, DSAPIException, com.isode.service2.ServiceException
      Create a DSA based on the given DSACreationTemplate.
      Parameters:
      ct - DSACreationTemplate to use for creation (not null)
      Returns:
      List of bind profiles that can be used to bind to the directory after creation. The first in the list is the bind profile used to bind as a managed user (which could be the superuser). The list will never be null. It will always at least have one bind profile which is of the managed user. These profiles should be added to the bind profile list and saved to disk if required.
      Throws:
      IOException - I/O related problem whilst creating or starting DSA
      DSAPIException - Directory-data or directory-communication problem whilst creating or starting DSA
      com.isode.service2.ServiceException - Service-related problem whilst creating or starting DSA

    • createFromTemplate

      public static List<BindProfile> createFromTemplate(DSACreationTemplate ct, AccessPoint masterAP, IsodeDirectorySession shadowMasterDS, DSASetup.UpgradeInfo upgradeInfo) throws IOException, DSAPIException, com.isode.service2.ServiceException
      Create a DSA based on the given DSACreationTemplate.
      Parameters:
      ct - DSACreationTemplate to use for creation (not null)
      masterAP - Access point of master if this is a failover, shadow or multimaster replica DSA creation, or null for normal DSA creation
      shadowMasterDS - non-null Isode directory session of the master DSA if this is shadow DSA creation; must be null if this is not shadow DSA creation. The session should have all config data loaded.
      upgradeInfo - Upgrade info, non-null only for creating an upgraded DSA, null otherwise.
      Returns:
      List of bind profiles that can be used to bind to the directory after creation. The first in the list is the bind profile used to bind as a managed user (which could be the superuser). The list will never be null. It will always at least have one bind profile which is of the managed user. These profiles should be added to the bind profile list and saved to disk if required.
      Throws:
      IOException - I/O related problem whilst creating or starting DSA
      DSAPIException - Directory-data or directory-communication problem whilst creating or starting DSA
      com.isode.service2.ServiceException - Service-related problem whilst creating or starting DSA

    • createBP

      public static BindProfile createBP(File dsa_dir, PresentationAddress address, BindProfileAddress bpa, String passwd, DN name, String label) throws BadSyntaxException
      Create a manager bind profile able to bind as the superuser to the DSA, and also to manage the DSA in D3M. To allow management, the bind profile stores additional information related to the DSA's configuration.
      Parameters:
      dsa_dir - Folder where DSA has been created (not null)
      address - PresentationAddress (not null)
      bpa - BindProfileAddress, or null to derive it from 'address'.
      passwd - Superuser password (not null)
      name - DSA name DN (not null)
      label - Label for profile (not null)
      Throws:
      BadSyntaxException - in case of invalid presentation address

    • createUserBP

      public static BindProfile createUserBP(PresentationAddress address, BindProfileAddress bpa, DN dn, String passwd, String label) throws BadSyntaxException
      Create a user bind profile for the given user and password. This bind profile does not support management of the DSA in D3M; it is just for binding in Sodium and other DUAs.
      Parameters:
      address - PresentationAddress (not null)
      bpa - BindProfileAddress, or null to derive it from 'address'.
      dn - User DN (not null)
      passwd - User password (not null)
      label - Label for profile (not null)
      Throws:
      BadSyntaxException - in case of invalid presentation address

    • createDSA

      public static void createDSA(File dsa_dir, PresentationAddress address, String passwd, DN name, GDAMType gdam_type) throws IOException
      Create a DSA using D3.
      Parameters:
      dsa_dir - Filesystem pathname of folder to create (not null).
      address - Presentation address (not null).
      passwd - Password to set for superuser (not null).
      name - DSA name (not null).
      Throws:
      IOException - if DSA creation was aborted or failed.

    • createDSA

      public static void createDSA(File dsa_dir, PresentationAddress address, String passwd, DN name, GDAMType gdam_type, DN prefix, DN failover, PresentationAddress meshInitPA, AccessPoint superiorAP) throws IOException
      Create a DSA using D3.
      Parameters:
      dsa_dir - Filesystem pathname of folder to create (not null).
      address - Presentation address (not null).
      passwd - Password to set for superuser (not null).
      name - DSA name (not null).
      prefix - DN of a top-level entry to create, or null to not create any top-level entry (apart from cn=config).
      failover - Master DN for failover configuration, or null for no failover.
      meshInitPA - Address of MESH server that will perform initial sync, otherwise null
      superiorAP - Access point of superior reference, if there is one; otherwise null
      Throws:
      IOException - if DSA creation was aborted or failed.

    • deleteDSA

      public static void deleteDSA(BindProfile bp, int gracePeriod) throws IOException
      Delete the DSA from the filesystem, if it is present. Note that the DSA must be stopped before this is done, or otherwise on Windows the deletion fails.

      On Windows, it has been observed that the files in the DSA's directory may still be held open for some time after the DSA has stopped. To work around this, gracePeriod should be used to specify how long to keep trying before giving up.

      Parameters:
      bp - BindProfile which must not be null
      gracePeriod - (only used on Windows) an attempt will be made to delete the DSA's directory every second until either gracePeriod is reached, or the directory is successfully deleted.
      Throws:
      IOException - in case of failure to delete one or more files (which may follow several attempts if gracePeriod was used), or if the bind profile doesn't specify a DSA directory

    • createService

      public static void createService(BindProfile bp) throws com.isode.service2.ServiceException
      Create a service for the DSA on Windows or Solaris, and add the service name to the bind profile.
      Parameters:
      bp - BindProfile
      Throws:
      com.isode.service2.ServiceException - if unable to create service

    • deleteService

      public static void deleteService(BindProfile bp) throws com.isode.service2.ServiceException
      Delete the service on Windows or Solaris, if it was setup, and clear the service name from the bind profile.
      Parameters:
      bp - BindProfile
      Throws:
      com.isode.service2.ServiceException - if unable to delete service

    • startDSA

      public static void startDSA(BindProfile bp) throws IOException, com.isode.service2.ServiceException
      Start a DSA identified by its bind profile.
      Parameters:
      bp - BindProfile
      Throws:
      IOException - Error whilst starting DSA on UNIX
      com.isode.service2.ServiceException - Service-related problem starting DSA

    • stopDSA

      public static void stopDSA(BindProfile bp) throws IOException, com.isode.service2.ServiceException
      Stop the DSA associated with this BindProfile
      Parameters:
      bp - BindProfile
      Throws:
      IOException - Error whilst stopping DSA on UNIX
      com.isode.service2.ServiceException - Service-related problem stopping DSA

    • getBestLocalPA

      public static PresentationAddress getBestLocalPA(boolean withMesh)
      Returns default presentation address (non-null) created using the local host name obtained. Will contain an ITOT address for port 19999 and an LDAP address for port 19389.
      Parameters:
      withMesh - Whether to include a multimaster address component.
      Returns:
      default presentation address (non-null)

    • getShadowTemplate

      public static DSACreationTemplate getShadowTemplate(DN bindDN, String password, DN masterDN)
      Returns DSA creation template for use when creating a shadow DSA. Will contain DSA DN and default presentation address. If the master's bind DN for a simple bind is provided, then the provided bind DN and password are used for the management bind profile, otherwise the bind profile is created for the super user.
      Parameters:
      bindDN - bind DN associated with the bind profile of the master used to create this DSA, null if master's bind profile is not for a simple bind
      password - non null password that will be used when performing a simple bind with the above bind DN, ignored if bindDN is null. Also ignored if bind DN is super user, in which case a new password would be generated.
      masterDN - DN of master, can not be null
      Returns:
      mirror DSA creation template

    • getMirrorTemplate

      public static DSACreationTemplate getMirrorTemplate(DN bindDN, String password, DN masterDN)
      Returns DSA creation template for use when creating a failover DSA. Will contain DSA DN and default presentation address. If the master's bind DN for a simple bind is provided, then the provided bind DN and password are used for the management bind profile, otherwise the bind profile is created for the super user.
      Parameters:
      bindDN - bind DN associated with the bind profile of the master used to create this DSA, null if master's bind profile is not for a simple bind
      password - non null password that will be used when performing a simple bind with the above bind DN, ignored if bindDN is null. Also ignored if bind DN is super user, in which case a new password would be generated.
      masterDN - DN of master, can not be null
      Returns:
      mirror DSA creation template

    • getReplicaTemplate

      public static DSACreationTemplate getReplicaTemplate(DN bindDN, String password, DN masterDN, PresentationAddress meshInitPA)
      Returns multimaster replica DSA creation template. Will contain DSA DN and default presentation address. If the master's bind DN for a simple bind is provided, then the provided bind DN and password are used for the management bind profile, otherwise the bind profile is created for the super user.
      Parameters:
      bindDN - Bind DN associated with the bind profile of the master used to create this DSA, null if master's bind profile is not for a simple bind.
      password - Non-null password that will be used when performing a simple bind with the above bind DN, ignored if bindDN is null. Also ignored if bind DN is super user, in which case a new password would be generated.
      meshInitPA - Address of multimaster server that will provide initial sync, cannot be null.
      Returns:
      Replica DSA creation template.

    • getUpgradeTemplate

      public static DSACreationTemplate getUpgradeTemplate(String password, DN dsaDN, PresentationAddress pa)
      Returns upgrade DSA creation template for use when upgrading a DSA. Will contain DSA DN, presentation address and superuser password of DSA to be upgraded.
      Parameters:
      password - superuser password of the DSA that is being upgraded, can not be null
      dsaDN - DN of DSA, can not be null
      pa - Presentation address of DSA, can not be null
      Returns:
      upgrade DSA creation template

    • setNCList

      public static void setNCList(IsodeDirectorySession shadowMasterDS, DSACreationTemplate ct)
      Set up the consumed naming context list in the template of a shadow DSA according to the naming contexts of the supplier. This does not add the cn=config naming context to the list. It marks all naming contexts as TRUE to be selected which can be modified later. The gdam field remains null and needs to be set later.
      Parameters:
      shadowMasterDS - non-null Isode directory session of the master DSA if this is shadow DSA creation; null if this is not shadow DSA creation. The session should have all config data loaded. If null, then this method returns without doing anything.
      ct - DSA creation template, must not be null.

    • getMandatoryNC

      public static DSACreationTemplate.NamingContext getMandatoryNC(DSACreationTemplate ct)
      Determines for a shadow server the naming context that is mandatory to consume because it contains the manager DN.
      Parameters:
      ct - DSA creation template that contains the information like manager DN, must not be null
      Returns:
      naming context that contains manager DN, null if manager DN is null

    • saveBPs

      public static void saveBPs(BindProfileList bpl, List<BindProfile> bpList) throws OperationFailedException, IOException
      Add bind profiles to Isode bind profile list and save the list to disk. If the list is simultaneously updated by another application, and the user decides to reload that version, this method tries to add the profiles to the list and save it to disk once more.
      Parameters:
      bpl - Isode bind profile list to add and save, must not be null
      bpList - list of bind profiles to add to Isode bind profile list above, must not be null
      Throws:
      OperationFailedException - if a profile already exists with the access point with same DSA DN as in the given bind profile.
      IOException - if this is a read-only BindProfileList, or if an error occurred when writing to the file (including if one of the BindProfile objects relies on functionality which is not supported for this version of file)