A virtual directory can be created by Plesk Administrator only. A virtual directory is created to map an existing physical directory of the site hosted on the specified site. The name of the virtual directory is specified as a relative path of this physical directory (the details follow).

A virtual directory obtains a collection of useful features (virtual directory settings) as follows:

  • Virtual directory properties are a collection of common settings (access, logging, or others)
  • Web application properties are specified to make the web server manages the virtual directory as a web application
  • Default page properties specify the display a default page when the virtual directory is accessed by default (no particular page is specified)

If not specified, the default virtual directory settings will be set up. See the Virtual Directory Settings section for details.

You can create one to many virtual directories with a single packet, including multiple virtual directories for the same physical directory. If the specified virtual directory maps a non-existing physical one, it will be created on the virtual host.

Mapping Issues

Assume that we have a site named mysite and want to map the site hosted on this site. We can create a virtual directory with the specified name (e.g. /vd1), and it will map the root directory of the site (...\vhost\mysite\httpdocs). In addition, we can create more virtual directories within the created one (e.g. /vd1/vd2). This operation will create a physical directory of the same name (vd2) within the root of the site (...\vhost\mysite\httpdocs\vd2), and this virtual directory will map the new physical one.

The following table demonstrates how the specified name of the virtual directory affects the mapping:

Virtual directory name The mapped physical folder Comment
/ ...\vhost\mysite It maps the root of the site.
/vd1 ...\vhost\mysite\httpdocs It maps the root of the site hosted on the site.
/vd1/vd2 ...\vhost\mysite\httpdocs\vd2 The /vd2 virtual directory is nested within the /vd1 one. Creating /vd2 means the creation of the /vd2 physical folder within \vhost\mysite\httpdocs mapped by /vd1.

Request Packet Structure

A request XML packet that creates a virtual directory should include the create operation node:

<packet>
<virtdir>
   <create>
   ...
   </create>
</virtdir>
</packet>

The create node is presented by type CreateVDirInputType (virtdir.xsd). Its graphical representation is as follows:

image 34269

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • The site-id node is required. It holds the identifier of the site that owns the virtual directory. Data type: integer.
  • The subdomain-id node is required. it holds the identifier of the subdomain that owns the virtual directory. Data type: integer.
  • The name node is required. It holds the name of the virtual directory. Data type: VDirPath (common.xsd).
  • The properties node is required. It holds a collection of virtual site settings. Data type: VDirProperties (virtdir.xsd). To see the structure of this node, refer to the Virtual Directory Properties section.

Note: When creating request packets, put nodes and elements in the order they follow in the packet structure.

Response Packet Structure

The create node of the output XML packet is structured as follows:

image 34293

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • The result node is required. It wraps the result of the create operation. Data type: resultType (common.xsd).
  • The status node is required. Specifies the execution status of the create operation. Data type: string. Allowed values: ok|error.
  • The errcode node is optional. Is required if the create operation fails. Returns the error code. Data type: unsignedInt.
  • The errtext node is optional. Can be returned if the create operation fails. Returns the error message. Data type: string.

Samples

Creating a single virtual direcrory

The following request packet creates a virtual directory with default properties on the specified site:

<packet>
<virtdir>
<create>
   <site-id>1</site-id>
   <name>/my_vdir</name>
   <properties/>
</create>
</virtdir>
</packet>

Response:

<packet>
<virtdir>
<create>
    <result>
       <status>ok</status>
    </result>
</create>
</virtdir>
</packet>

Creating multiple virtual directories

To create multiple virtual directories with a single packet, use a different <create> section for each:

<packet>
<virtdir>
<create>
   <site-id>1</site-id>
   <name>/my_vdir</name>
   <properties/>
</create>
<create>
   <site-id>2</site-id>
   <name>/my_vdir</name>
   <properties/>
</create>
</virtdir>
</packet>

f the request packet creates multiple virtual directories, the result of each create operation will be returned in a different create section:

<packet>
<virtdir>
<create>
    <result>
       <status>ok</status>
    </result>
</create>
<create>
    <result>
       <status>ok</status>
    </result>
</create>
</virtdir>
</packet>

The create nodes will follow one another in the order they have been sent within the request packet.