Creating FTP Accounts

To create an FTP account on a site, use the add operation. The number of accounts that can be created on a particular site is restricted with the 'Maximum number of additional FTP accounts site limit, or/and by customer limit of the same name.

Note: Plesk customers can specify quota on disk space used by home directory only if they are granted the Hard disk quota assignment permission.

In this chapter:

Request Packet Structure

Response Packet Structure

Samples

 

Request Packet Structure

A request XML packet creating FTP account on a site includes the add operation node:

<packet>
<ftp-user>
   <add>
   ...
   </add>
</ftp-user>
</packet>

 

The add node is presented by the FtpUserAddInputType complex type (ftpuser.xsd). The node has the following graphical representation:

domainGenInfoType

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 name node is required. It specifies the name under which the FTP account will be known in Plesk, and the account login. The name must start with a lowercase alphabetic character, consist only of lowercase alphanumeric, dash, and underscore symbols, and be between 1 and 16 characters in length. Data type: string.
  • The password node is required. It specifies the FTP account password. Data type: string.
  • The home node is required. It specifies the home directory of the account, i.e., the directory access to which is granted for the account user. Data type: string.
  • The create-non-existent node is optional. It specifies if the home directory should be created or not. This node with value true is required if the home directory defined by the home node does not exist on the site. Data type: boolean.
  • The quota node is optional. It specifies the maximum total size of files and folders (in bytes) that the FTP account user can create in or upload to the home directory. Data type: integer.
  • The permissions node is optional. It specifies the FTP account permissions for home directory. For more information, refer to section FTP Account Permissions. Data type: FtpUserPermissions.
  • The webspace-id node is required. It specifies the ID of the site on which the FTP account is created. Data type: integer.
  • The webspace-name node is required. It specifies the name of the site (in unicode) on which the FTP account is created. Data type: string.

 

Remarks

1. FTP account name must be unique in Plesk, meaning that two FTP accounts with the same name cannot be crated, even if you want to crate them on different sites.

2. The default home directory for any new additional FTP account is the site root directory (namely, "/"). If you want FTP account created with request packet to have a default home directory, include an empty home node to your request:

<home/>

If you want to specify account home directory other than default, in the home node specify a full path to desired directory, starting with root site directory. For example:

<home>/httpdocs/billy/pub</home>

 

3. Creating new folders in the site's root directory is prohibited by Plesk. Therefore, it is impossible to make some /Global_Upload folder a home directory for an account. Do not include to your packets lines like

<home>/Global_Upload</home>
<create-non-existent>true</create-non-existent>

 

4. To create FTP account with unlimited quota, specify value "-1" in the quota node:

<quota>-1</quota>

 

5. With one add operation, you can create only one FTP account on a site specified either by name or by ID.

6. With one packet, you can create as many different FTP accounts on different sites as you want. To create multiple FTP accounts, use the required number of add nodes in the packet.

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

 

Response Packet Structure

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

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 response received from the server. Data type: FtpUserSimpleResultType (ftpuser.xsd).
  • The status node is required. Specifies the execution status of the add operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. Is used to return the error code when the add operation fails. Data type: unsignedInt.
  • The errtext node is optional. Is used to return the error message if the add operation fails. Data type: string.
  • The id node is required if the operation succeeds. It returns the unique identifier of the FTP account created with the add operation. Data type: integer.
 

Samples

Creating single FTP account on a site

This packet creates FTP account, with only required settings specified, on site with ID "48". The FTP account created with this packet will have name and login ftpuser1 and password jdnHHbe6Gc. User of this account will have access to the site directory httpdocs, with unspecified permissions. Total size of files that this FTP user is allowed to upload will be limited to default values defined by site or site owner limits.

<packet>
<ftp-user>
<add>
   <name>ftpuser1</name>
   <password>jdnHHbe6Gc</password>
   <home/>
   <webspace-id>1</webspace-id>
</add>
</ftp-user>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <ftp-user>
    <add>
      <result>
        <status>ok</status>
        <id>1</id>
      </result>
    </add>
  </ftp-user>
</packet>
Creating multiple FTP accounts

This packet creates three FTP accounts on site example.com. Two of these accounts will have read and write permissions on accessing directory Incoming located in folder /private/photoshare which does not exist on the site and which will be created with this request packet. The third user created with the packet will have only read permission on accessing the same directory. Total size of files that the FTP users are allowed to upload will be limited to 100 Mbytes.

<packet>
<ftp-user>
<add>
   <name>photo1</name>
   <password>dkfje44Fwen</password>
   <home>/private/photoshare/Incoming</home>
   <create-non-existent>true</create-non-existent>
   <quota>104857600</quota>
   <permissions>
      <read>true</read>
      <write>true</write>
   </permissions>
   <webspace-name>example.com</webspace-name>
</add>
<add>
   <name>photo2</name>
   <password>jrtd30fH33</password>
   <home>/private/photoshare/Incoming</home>
   <quota>104857600</quota>
   <permissions>
      <read>true</read>
      <write>true</write>
   </permissions>
   <webspace-name>example.com</webspace-name>
</add>
<add>
   <name>photo3</name>
   <password>J7chhend</password>
   <home>/private/photoshare/Incoming</home>
   <permissions>
      <read>true</read>
      <write>false</write>
   </permissions>
   <webspace-name>example.com</webspace-name>
</add>
</ftp-user>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <ftp-user>
    <add>
      <result>
        <status>ok</status>
        <id>2</id>
      </result>
    </add>
    <add>
      <result>
        <status>ok</status>
        <id>3</id>
      </result>
    </add>
    <add>
      <result>
        <status>ok</status>
        <id>4</id>
      </result>
    </add>
  </ftp-user>
</packet>
 

Leave your feedback on this topic here

If you have questions or need support, please visit the Plesk forum or contact your hosting provider.
The comments below are for feedback on the documentation only. No timely answers or help will be provided.