2.5.2.3 Create DFS Link

  • Article

Goal

To create a DFS link for access by using SMB access protocols with extensions, as described in [MS-DFSC].

Context of Use

The administrator is setting up a file server or is maintaining a namespace on an existing file server.

Actors

  • Admin tool

    The admin tool is the primary actor that triggers this use case. The admin tool is a program that offers management functionality to the administrator through the admin client. Typical admin tools are command-line tools and graphical shells, management utilities, and graphical management programs. The purpose of the admin tool is to correctly interpret, execute, and display the results of the commands that are issued by the administrator.

  • DFS Service

    The DFS Service is a supporting actor that provides the technology that helps administrators group shared folders that are located on different servers and present them to users as a virtual tree of folders that is known as a namespace.

  • Admin client

    The admin client is a supporting actor that implements client-side protocol components and consumes the file server administration services that are offered by the file server. The admin client is internal to the File Services Management system.

  • Authentication Services

    The Authentication Services is the supporting actor that is used for authentication purposes.

  • Active Directory system

    The Active Directory system is a supporting actor. The File Services Management system stores metadata that is related to the domain DFS namespace in Active Directory.

Stakeholders

  • Administrator

    The administrator is the person who administers the file server. The administrator has administrative rights and uses the File Services Management system to provide the SMB File Service.

Preconditions

The administrator has identified an SMB File Service that hosts an instance of the given namespace, the SMB share on the SMB File Service that hosts the given namespace, the path in the share at which the link is created, and the target that the link refers to. A DFS Service is present on the SMB File Service, as described in [MS-DFSNM].

Main Success Scenario

  1. Trigger: The admin tool receives a request from the administrator to create a DFS link on the SMB File Service.

  2. The admin tool establishes a communication channel to DFS Service, as described in [MS-DFSNM] section 2.1.

  3. The DFS Service authenticates the administrator through the mechanisms, as described in [MS-AUTHSOD].

  4. The admin tool contacts the DFS Service by using the NetrDfsAdd method ([MS-DFSNM] section 3.1.4.1.3) to create the link within the namespace, which also creates the DFS link object in the local object store.

  5. The DFS Service authorizes the administrator through the mechanisms of the NetrDfsAdd method, as described in [MS-DFSNM] section 3.1.4.1.3.

  6. The DFS Service performs the action.

Postcondition

The specified DFS link is created within the given DFS namespace on the SMB File Service along with corresponding metadata that is written to the Active Directory system in the case of a domain DFS namespace.

Extensions

If the communication channel for the DFS namespace, as described in [MS-DFSNM], cannot be established, or it becomes disconnected:

  • The admin tool can attempt to establish connection multiple times; ultimately, the use case ends with failure. Depending on when the connection failed, the link could or could not have been created.

If user authorization or authentication fails:

  • The use case ends with failure.

In the case of a domain DFS namespace:

  • The DFS Service additionally interacts with the Active Directory system, as described in [MS-ADOD] to store metadata changes that are related to the DFS link, as described in [MS-DFSNM].