3.3 Example 3: Creating and Managing a DFS Domain Namespace

  • Article

This example demonstrates the use cases described in section 2.5.2.2, section 2.5.2.3, and section 2.5.2.4.

Prerequisites

  • The participating client and server computers are configured to belong to the same Active Directory domain.

  • A share is created on the file server.

  • Clients and Distributed File System (DFS) servers have access to the Active Directory system that is provided by the domain.

  • The application has acquired a remote procedure call (RPC) calling context for DFS Service by using the procedure as described in [MS-DFSNM] section 2.1.

  • The application has acquired an RPC calling context for File Replication Service (FRS) Service by using the procedure as described in [MS-DFSRH] section 2.1.

Initial System State

None.

Final System State

The specified local path on the file server functions as a DFS namespace with a single link.

This example is divided into three tasks:

  • Creating a DFS domain namespace

  • Creating a DFS link

  • Creating a replication group

The following sequence diagram shows the steps to create and manage a DFS domain namespace.

Sequence diagram for creating and managing a namespace

Figure 13: Sequence diagram for creating and managing a namespace

  1. CreateNamespace: The administrator requests that the admin tool creates a DFS namespace on the previously configured SMB share. The admin tool specifies the server, the share name, and various other options that are specific to the creation of the namespace.

  2. Create DFS Namespace: The admin tool makes use of the admin client to create a DFS namespace. The sequence of steps is described in Task 1: Creating a DFS domain namespace.

  3. CreateLink: The administrator requests that the admin tool create a DFS link in the DFS namespace. The admin tool specifies the server and share name of the namespace, the path at which the link is created, the target of the link, and various other options that are specific to creating the link.

  4. Create DFS Link: The admin tool makes use of the admin client to create a DFS link. The sequence of steps is described in Task 2: Creating a DFS Link.

  5. CreateReplicationGroup (Optional): The administrator requests that the admin tool creates an FRS replica group. It specifies the domain controller and the group members.

  6. Create DFS-R Replication group (Optional): The admin tool makes use of the admin client to create a replication group. The sequence of steps is described in Task 3: Creating a Replication Group (Optional).

Note: The admin tool uses the NetrDfsEnum method ([MS-DFSNM] section 3.1.4.1.7), or the NetrDfsEnumEx method ([MS-DFSNM] section 3.1.4.2.3) to enumerate the DFS root that is hosted on a server or the DFS links of the namespace that are hosted by a server. The admin tool calls the NetrDfsManagerGetVersion method ([MS-DFSNM] section 3.1.4.1.2) to determine the enumeration method to use. The admin tool calls these enumeration methods multiple times to refresh its list.

Task 1: Creating a DFS Domain Namespace

The following example describes the steps that are used to create a DFS domain namespace. The DFS service that is used in this example resides on the root target server.

The following sequence diagram shows the steps to create a DFS domain namespace.

Sequence diagram for creating a DFS domain namespace

Figure 14: Sequence diagram for creating a DFS domain namespace

  1. The admin client calls the NetrDfsAddRootTarget method ([MS-DFSNM] section 3.1.4.1.9). The admin client specifies the server, the share to host the namespace, and various options that are provided by the administrator.<1>

  2. The DFS Service creates a new DFS namespace Lightweight Directory Access Protocol (LDAP) entry with the DFS namespace anchor LDAP entry as its parent. The server also creates the DFS metadata that is required for the new DFS namespace and updates the DFS metadata in the object that corresponds to the DFS namespace. This update appears as an LDAP Add operation to the domain controller.

  3. The DFS metadata write operation is successful, and the domain controller returns LDAP_SUCCESS to indicate success.

  4. The DFS Service completes the NetrDfsAddRootTarget method and returns a success code to the admin client.

    Task 2: Creating a DFS Link

    The following example describes the steps that are used to add a new DFS link to an existing domainv2-based DFS namespace with one root target. The DFS service that is used in this example resides on the root target server.

    The following sequence diagram shows the steps to add a DFS link.

    Sequence diagram for adding a DFS link

Figure 15: Sequence diagram for adding a DFS link

  1. The admin tool requests the admin client to create the given DFS link in the DFS namespace, which is hosted by the server that is identified in the RPC calling context. The admin client calls the NetrDfsAdd method ([MS-DFSNM] section 3.1.4.1.3) that specifies the link path, target, and other options.

  2. The DFS service verifies the existence of the namespace name and the link ([MS-DFSNM] section 3.1.4.1.3).

  3. The DFS service issues an LDAP Add request to the domain controller with the updated DFS metadata that contains the new DFS link information for a domainv2-based DFS namespace ([MS-DFSNM] section 3.1.4.1.3).

  4. The LDAP Add operation is successful and the LDAP server returns an LDAP_SUCCESS message to the DFS service.

  5. The NetrDfsAdd method that is invoked by the admin client finishes successfully. The DFS service returns a success code to the admin client.

    Task 3: Creating a Replication Group (Optional)

    The following example describes the steps to create a replication group on a domain controller.

    The following sequence diagram shows the steps to create a replication group.

    Sequence diagram for creating a replication group

Figure 16: Sequence diagram for creating a replication group

  1. The admin client calls the CreateObject method of the DFS-R Service that passes the domain controller name and the replica members by using the IADProxy::CreateObject method<2>, as described in [MS-DFSRH] section 3.1.5.2.1, or by using the IADProxy2::CreateObject method ([MS-DFSRH] section 3.1.5.3.1).

  2. The DFS-R Service uses LDAP messages to create the replication object on the domain controller ([MS-DFSRH] section 3.1.5.2.1).

  3. After getting the success response from the domain controller, the DFS-R Service sends a success code to the admin client.