The set operation is used to change settings of additional FTP accounts existing in Plesk database. You can change settings of particular FTP accounts, or of all FTP accounts existing on particular sites or in the whole Plesk database, depending on what Plesk user credentials are specified in HTML headers of request packet.

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

Request Packet Structure

A request XML packet changing FTP account settings in the Plesk database includes the set operation node:

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

The set node is presented with the FtpUserSetInputType complex type (ftpuser.xsd), its graphical representation is as follows:

image 35326

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 filter node is required. It indicates FTP accounts which settings are to be updated with the information specified in values node. Data type: FtpUserFilterType (ftpuser.xsd). For information on this node structure, refer to Available Filters.
  • The values node is required. It wraps a collection of settings that will be applied to the accounts specified with filter node. Data type: FtpUserSetType (ftpuser.xsd).
  • The name node is optional. It specifies the new name under which the FTP account will be known in Plesk, and the new 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 optional. It specifies the new FTP account password. Data type: string.
  • The home node is optional. It specifies the new 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 new home directory should be created or not. This node with value true is required if new home directory defined with the home node does not exist. 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.

Remarks

1. The home node should contain a full path to FTP account home directory starting with root site directory. For example: /httpdocs/billy/pub. If the home node is left blank (<home/>), then home directory for FTP account will be set to default one, which is the site’s root directory.

2. Creating new folders in site 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>

3. To change FTP account quota to unlimited, specify value “-1” in the quota node:

<quota>-1</quota>

4. With one packet, you can change settings of as many different FTP accounts with different filtering rules as you want. To do so, use the required number of add nodes in the packet.

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

Response Packet Structure

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

image 35331

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: r esultFilterType (ftpuser.xsd).
  • The status node is required. Specifies the execution status of the set operation. Data type: string. Allowed values: ok | error.
  • The errcode node is optional. Is used to return the error code when the set operation fails. Data type: unsignedInt.
  • The errtext node is optional. Is used to return the error message if the set operation fails. Data type: string.
  • The filter-id node is optional. It returns the filtering rule. For more information, refer to the Available Filters section.
  • The id node is required if the operation succeeds. It returns the unique identifier of the FTP account which settings were modified with add operation in request packet. Data type: integer.

Samples

Changing password for a single FTP account

This packet sets up new password for FTP account with name “ftpuser2”.

<packet>
<ftp-user>
<set>
   <filter>
      <name>ftpuser2</name>
   </filter>
   <values>
      <password>jkRR67hVBB</password>
   </values>
</set>
</ftp-user>
</packet>

Response:

<packet>
<ftp-user>
<set>
   <result>
      <status>ok</status>
      <filter-id>ftpuser2</filter-id>
      <id>6</id>
   </result>
</set>
</ftp-user>
</packet>

Creating new account home directory for an FTP account

This packet updates settings of FTP account with ID 1: It creates new account home directory /httpdocs/Pub and allows read and write permissions.

<packet>
<ftp-user>
<set>
   <filter>
      <id>1</id>
   </filter>
   <values>
      <home>/httpdocs/Pub</home>
      <create-non-existent>true</create-non-existent>
      <permissions>
         <read>true</read>
         <write>true</write>
      </permissions>
   </values>
</set>
</ftp-user>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <ftp-user>
    <set>
      <result>
        <status>ok</status>
        <filter-id>1</filter-id>
        <id>1</id>
      </result>
    </set>
  </ftp-user>
</packet>

Changing settings of multiple FTP accounts

This packet is incorrect as it intends to give the same new name to all FTP accounts existing on the subscription with ID 1.

<packet>
<ftp-user>
<set>
  <filter>
     <webspace-id>1</webspace-id>
  </filter>
  <values>
     <name>ftp-doe1</name>
  </values>
</set>
</ftp-user>
</packet>

Response:

<?xml version="1.0" encoding="UTF-8"?>
<packet version="1.6.7.0">
  <ftp-user>
    <set>
      <result>
        <status>ok</status>
        <filter-id>1</filter-id>
        <id>1</id>
      </result>
    </set>
  </ftp-user>
</packet>