Differences
This shows you the differences between the selected revisions of the page.
| resume 2005-04-26 | resume 2023-12-07 (current) | ||
| Line 1: | Line 1: | ||
| - | ====== Transfer Resume ====== | + | ====== File Transfer Resume ====== |
| ===== Basic Usage ===== | ===== Basic Usage ===== | ||
| - | WinSCP supports resuming file transfers with [[protocols|SFTP protocol]] only. SCP protocol does not allow it at all. | + | WinSCP supports resuming file transfers with [[SFTP]] and [[FTP]] protocols. [[SCP]] and [[WebDAV]] protocols do not allow it. With [[S3]] protocol, transfer can be resumed only immediately by reconnecting a lost session, not later. |
| - | For performance reasons resuming file transfer is supported only for files larger then a given threshold. By default the threshold is 100 kB. This can be configured on //[[ui_pref_resume|Resume tab]]// of Preferences dialog. Also resuming text/ascii mode transfers is not supported. | + | ===== [[automatic]] Automatic Resume / Transfer to Temporary Filename ===== |
| + | WinSCP is able to store file being transferred to temporary filename first, renaming it to the target name only once the transfer successfully finishes. | ||
| - | When transfering file, it is first transfered into a temporary file with ''.filepart'' extension. Only after the transfer is completed the extension is removed. | + | Reasons to do that: |
| + | * If the transfer is interrupted, on the next attempt (either manual or automatic), WinSCP is able to automatically detect the partial/temporary file and offer you to resume the transfer (or even resume automatically). | ||
| + | ··* While updating an existing file, the original version of the file exists during whole transfer. This is particularly useful when updating frequently accessed file on web sites. | ||
| + | * If the server runs a process that automatically picks new files and processes them, it can be configured to ignore distinct names of temporary files. It prevents the process from picking an incomplete file, while it's uploaded. See [[script_locking_files_while_uploading|locking files while uploading]]. | ||
| - | If the transfer is interrupted, by user or because of dropped connection, partial file (with ''.filepart'' extensions) remains in the target folder. Once you attempt to transfer the same file again, WinSCP looks for the partial file. If it finds any, it offers you chance to resume the transfer ([[ui_pref_environment#confirmations|the confirmation can be disabled]]). | + | Reasons not to do that: |
| + | * As the file is uploaded to a temporary name, it is technically a new file, even though the file with target name already exists. As such: | ||
| + | ···* after the original file is deleted and temporary file is renamed to the original file name, you lose all attributes of the original file (such as owner and group) except for basic permissions;((For this reason WinSCP never transfers to temporary file name first, if the target file is know to be owner by another user. Note that the owner name can be detected with SFTP-4 and newer only.)) | ||
| + | ····* while you may have permissions to overwrite the existing file, you might not have permissions to create new (temporary) file. | ||
| - | Note that partial files can be distinguished by special [[ui_file_panel#special_files|"teared sheet" overlay icon]]. | + | For performance reasons transfer to temporary file name is enabled by default for files larger than a given threshold. The threshold is initially 100 KB. You can change the threshold. You can also enable the feature for all files, particularly when looking to achieve the second impact. You may also need to disable the feature altogether, particularly if you do not have permissions required (e.g. permissions to create a new file in target directory). This can be configured on //[[ui_pref_resume|Endurance page]]// of Preferences dialog. |
| - | ===== Alternate Usage ===== | + | If your transfer is interrupted, a partial file (with ''.filepart'' extension) remains in the target folder. After you try to transfer the file a second time, WinSCP looks for the partial file. If it finds a partial file, it offers you chance to resume the transfer ([[ui_pref_environment#confirmations|the confirmation can be disabled]]). |
| - | The above method of resuming file transfers is supported only for [[protocols|SFTP version 2]] and newer (most of the current SFTP servers). There is another method supported even for the older servers (but not for SFTP version 4 and newer for ASCII/text transfers). Even if your server supports SFTP version 2 and never, you may find the method useful. Note that you must have [[ui_pref_environment#confirmations|overwrite confirmations]] enabled to use the method. | + | |
| - | When you attempt to transfer file that already exists in target directory, the overwrite confirmation dialog is displayed. It offers //Append// button. By default it appends source file to the end of the target file. But if the target file is smaller then the source file, another prompt will be displayed offering you either to append source file or to resume transfer. If you select to resume transfer, the part of source file equal to size of the target file will be skipped and only the remaining part will be transfered.· | + | Note that partial files can be distinguished in file panel by special [[ui_file_panel#special_files|"torn sheet" overlay icon]]. |
| - | The method is particularly useful for resuming transfers initiated by other clients and also to update log files. | + | To configure transfer to temporary file name in [[scripting]], use ''-resumesupport'' ==switch== of file transfer commands (such as [[scriptcommand_put|''put'']], [[scriptcommand_get|''get'']], etc). In .NET assembly use ''[[library_transferoptions#resumesupport|TransferOptions.ResumeSupport]]''. |
| - | ===== Common Problems ===== | + | Transfer to temporary filename is supported with [[sftp|SFTP protocol]] only and only for [[transfer_mode|binary transfers]]. |
| - | It is on user responsibility that he/she resumes transfer with the same version of source file as the transfer was interrupted. Otherwise you will end with target file consisting partly of previous version and partly of current version of the source file. If the partial file is bigger than the source file, WinSCP will display error and disallow resume. | + | |
| - | If the target file already exists and it is not writeable, but the target directory is, the file will be transfered anyway. The error overwritting the file will occur only after the transfere finishes. It is because the file is first transfered into temporary file. | + | ===== [[manual]] Manual Resume ===== |
| + | There's an alternative manual method to resume transfer, which can be used with FTP protocol. | ||
| + | |||
| + | If you attempt to transfer a file already in the target directory and the target file is smaller then the source file, the [[ui_overwrite|overwrite confirmation dialog]] displays a //Resume// command or an //Append// command (when appending is supported), in the drop-down menu of the //No// button. After you click //Append//, WinSCP opens another prompt that lets you append source file or resume your transfer. | ||
| + | |||
| + | If you resume the transfer, WinSCP will skip a part of the source file equal to the target file's size. The program will only transfer the remainder. | ||
| + | |||
| + | Note that you must have [[ui_pref_environment#confirmations|overwrite confirmations enabled]] to use the method. | ||
| + | |||
| + | The method is also useful for resuming transfers initiated by other clients and also to update log files. Manual resuming of [[transfer_mode|text mode transfers]] with SFTP-4 and newer is not supported. | ||
| + | |||
| + | ===== [[common_problems]] Common Problems ===== | ||
| + | If you want to resume your transfer, you must use the same source file version as the interrupted transfer. If you do not, your target file will include the source file's previous version and its current version. For automatic resume, if the partial file is bigger than the source file, WinSCP will display error and disallow resume. | ||
| + | |||
| + | If the target file exists and it is not write-able, but the target directory is, the file will may be transferred anyway with automatic resume. The error overwriting the file will occur only after the transfer finishes. It is because the file is first transferred into temporary file. | ||
| + | |||
| + | ===== [[broken_connection]] Resuming from Broken Connections ===== | ||
| + | With [[sftp|SFTP]] and [[ftp|FTP]] protocols, when connection is broken, WinSCP can automatically reconnect and resume the transfer.((If transfer resuming/transfer to temporary files name is disabled, file transfer will start from the beginning, with [[sftp|SFTP protocol]].)) This can be configured on //[[ui_pref_resume|Endurance page]]// of Preferences dialog. | ||