This is an old revision of the document!

XML Logging

XML logging is one of the WinSCP log formats. XML log includes structured records describing operations done by WinSCP over session. The log format is protocol independent.

In many cases you do not have to deal with the XML log file directly. WinSCP .NET assembly can do it for you.

Purpose

Primary purpose of the XML logging is to provide machine-readable description of automatically performed operations, such as when using scripting.

XML logging is useful e.g. to:

Find a list of files that were actually uploaded/downloaded, when transferring whole directory or files matching a mask;
Get directory listing;
Record operations done during synchronization.

Note that while the XML logging can be used also for GUI sessions, it does not record a background transfers.

Using

XML logging, being used along with scripting, is most typically enabled from command-line, using /xmllog parameter. It can be enabled in preferences too.

Overall format of the XML log file follows:

<?xml version="1.0" encoding="UTF-8"?>
<session xmlns="http://winscp.net/schema/session/1.0"
         name="martin@example.com" start="2009-03-02T19:34:57.734Z">
  <!-- operations -->  
</session>

The top level session tag represents one logical session, which may consist of several physical sessions, particularly when connection is lost. Attribute name refers to name of the logical session. Attribute start indicates time when the session was initiated1.

The session element includes child elements, where each element represents single log entry, i.e. single physical operation with remote file over the logical session.

Representing Operations in Log

Every entry in XML log represents single physical operation over the session. Typically this would be an operation with remote file.

Single logical operation (in scripting or GUI) may actually involve multiple physical operations, each represented with separate log element. For example upload of file (e.g. using put scripting command) may be represented by up to three elements, upload for actual upload, touch for preserving timestamp and chmod for preserving permissions.

Note that some logical operations does not have corresponding log element (e.g. creation of symbolic link). Such operations are omitted from the XML log.

Representing Results/Errors

Results/Errors of Operations

Result of a specific operation is represented by child result element of respective operation element. The result element has boolean success attribute.

<result success="true" />

If success is false, result element will typically include one or more message elements with error message(s). The error message is free text, that may be language-, protocol- or even server-specific. So you should not try to process it automatically.

The following example is from English version, connected with SFTP protocol to OpenSSH server:

<result success="false">
  <message>Cannot open remote file '/home/user/examplefile.txt'.</message>
  <message>No such file or directory.
Error code: 2
Error message from server: No such file
Request code: 3</message>
</result>

With some protocols, each of the physical operations are performed individually. With some protocols, set of operations may be performed in atomic form. This may prevent mapping error to specific operation. In this case the error may be associated with more operations, resulting in its duplication in the XML log.

Some errors may not be associated with any operation in the XML log. This particularly happens when:

An error is actually not associated with particular physical operation. Example is invalid script command syntax.
The particular operation that failed does not have corresponding log element.

Results/Errors of Script

When the script fails (WinSCP exit code is 1), the top level session element or group element (when grouping is enabled) will include one or more failure elements, each containing one or more message elements with error message(s).

If the particular error was associated with a physical operation, the error message will be included both in result child element of the respective operation element and in failure child element of top level session element or group element.

<upload>
  <filename value="d:\examplefile.txt" />
  <result success="false">
    <message>Cannot create remote file '/home/user/examplefile.txt'.</message>
    <message>Permission denied.
Error code: 3
Error message from server: Permission denied
Request code: 3</message>
  </result>
</upload>
<failure>
  <message>Cannot create remote file '/home/user/examplefile.txt'.</message>
  <message>Permission denied.
Error code: 3
Error message from server: Permission denied
Request code: 3</message>
</failure>

Grouping Operations for Commands

When using XML logging together with scripting, operations and failures belonging to the same command can be grouped using parent group element:

<group name="put -preservetime d:\*.txt" start="2012-01-04T14:25:10.204Z">
  <upload>
    <filename value="d:\readme.txt" />
    <destination value="/home/user/readme.txt" />
    <result success="true" />
  </upload>
  <upload>
    <filename value="d:\examplefile.txt" />
    <result success="false">
      <message>Cannot create remote file '/home/user/examplefile.txt'.</message>
      <message>Permission denied.
Error code: 3
Error message from server: Permission denied
Request code: 3</message>
    </result>
  </upload>
  <failure>
    <message>Cannot create remote file '/home/user/examplefile.txt'.</message>
    <message>Permission denied.
Error code: 3
Error message from server: Permission denied
Request code: 3</message>
  </failure>
</group>

Grouping can be enabled on command-line.

Grouping is particularly useful, when you are continuously reading the XML log file. By receiving </group> you know that the command execution has finished.

Elements

All operation elements below have result child element in addition to listed child elements.

The result child element is always present. Many other child elements may be absent in case of error.

call

Execution of arbitrary remote shell command (with SFTP and SCP protocols) or execution of a protocol command (with FTP protocol).

Elements:

Element	Description
`command`	Command (in `value` attribute)
`destination`	Absolute path to current remote working directory (in `value` attribute)
`output`	Command standard output (in `value` attribute)
`erroroutput`	Command error output (in `value` attribute)

Example:

<call>
  <command value="ps" />
  <destination value="/home/user" />
  <output value="  PID TTY          TIME CMD
16969 ?        00:00:00 sshd
16970 ?        00:00:00 sftp-server
32647 ?        00:00:00 bash
 1466 ?        00:00:00 ps" />
  <result success="true" />
</call>

Associated script commands: call

checksum

Calculating a checksum of a remote file.

Elements:

Element	Description
`filename`	Absolute path to a remote file (in `value` attribute)
`algorithm`	Name of a checksum algorithm used (in `value` attribute)
`checksum`	Hex dump of a calculated checksum (in `value` attribute)

Example:

<checksum>
  <filename value="/home/martin/public_html/index.html" />
  <algorithm value="sha-1" />
  <checksum value="bb4dfa9b51d3f6c99b5ec6c12ebf9cade79f43c4" />
  <result success="true" />
</checksum>

Associated script commands: checksum

chmod

Changing of permissions of one (or more) remote file.

Elements:

Element	Description
`filename`	Absolute path to remote file (in `value` attribute)
`permissions`	Permissions in Unix format `rwxrwxrwx` (in `value` attribute)

With SCP protocol optional boolean attribute recursive indicates, if permissions were changed recursively with single operation.

Example:

<chmod recursive="true">
  <filename value="/home/martin/public_html/about.html" />
  <permissions value="rwxr-xr-x" />
  <result success="true" />
</chmod>

Associated script commands: chmod, keepuptodate -permissions, put -permissions, synchronize remote|both -permissions

download

Downloading of single file.

Elements:

Element	Description
`filename`	Absolute path to source remote file (in `value` attribute)
`destination`	Absolute path to destination local file (in `value` attribute)2

Example:

<download>
  <filename value="/home/martin/public_html/about.html" />
  <destination value="d:\www\about.htm" />
  <result success="true" />
</download>

Associated script commands: get, synchronize local|both

ls

Listing of remote directory (only when explicitly requested using ls scripting command).

Elements:

Element	Description
`destination`	Absolute path to remote directory (in `value` attribute)
`files`	Container of `file` elements

Elements of file element:

Element	Description
`filename`	Name of file without path (in `value` attribute)
`type`	Type of file as in Unix `ls` command output, e.g. `d` for directory (in `value` attribute)
`size`	Size of file in bytes (in `value` attribute)
`modification`	Modification timestamp (in `value` attribute)1
`permissions`	File permissions in Unix format `rwxrwxrwx` (in `value` attribute)
`owner`	File owner. This feature is available only in the latest beta release.
`group`	File group. This feature is available only in the latest beta release.

Example:

<ls>
  <destination value="/home/martin/public_html" />
  <files>
    <file>
      <filename value="." />
      <type value="d" />
      <modification value="2008-12-22T12:16:23.000Z" />
      <permissions value="rwxr-xr-x" />
    </file>
    <file>
      <filename value=".." />
      <type value="d" />
      <modification value="2008-03-25T08:15:53.000Z" />
      <permissions value="rwxr-xr-x" />
    </file>
    <file>
      <filename value=".htaccess" />
      <type value="-" />
      <size value="107" />
      <modification value="2008-12-02T06:59:58.000Z" />
      <permissions value="rw-r--r--" />
    </file>
    <file>
      <filename value="about.html" />
      <type value="-" />
      <size value="24064" />
      <modification value="2007-10-04T21:43:02.000Z" />
      <permissions value="rw-r--r--" />
    </file>
  </files>
  <result success="true" />
</ls>

Associated script commands: ls

mkdir

Creating of remote directory.

Elements:

Element	Description
`filename`	Absolute path to remote directory (in `value` attribute)

Example:

<mkdir>
  <filename value="/home/martin/public_html/images" />
  <result success="true" />
</mkdir>

Associated script commands: keepuptodate, mkdir, put, synchronize remote|both

mv

Moving or of one remote file or directory to different remote directory or renaming of one remote file or directory.

Elements:

Element	Description
`filename`	Absolute path to source local file (in `value` attribute)
`destination`	Absolute path to destination remote file (in `value` attribute)2

Example:

<mv>
  <filename value="/home/martin/public_html/about.html" />
  <destination value="/tmp/about.bak" />
  <result success="true" />
</mv>

Associated script commands: mv

rm

Deleting of one (or more) remote file or directory.

Elements:

Element	Description
`filename`	Absolute path to remote file of directory (in `value` attribute)

With SCP protocol optional boolean attribute recursive indicates, if remote directory was recursively deleted with all contained files with single operation.

Example:

<rm recursive="true">
  <filename value="/home/martin/public_html/images" />
  <result success="true" />
</rm>

Associated script commands: get -delete, keepuptodate -delete, rm, rmdir, synchronize local|both -delete

stat

Listing of remote file attributes.

Elements:

Element	Description
`filename`	Absolute path to remote file (in `value` attribute)
`file`	Container of file attributes. See specification in description of `ls` element. Note that `file` element within `stat` misses `filename` subelement, comparing to `file` element within `ls`/`files`.

Example:

<stat>
  <filename value="/home/martin/public_html/about.html" />
  <file>
    <type value="-" />
    <size value="24064" />
    <modification value="2007-10-04T21:43:02.000Z" />
    <permissions value="rw-r--r--" />
  </file>
  <result success="true" />
</stat>

Associated script commands: stat

upload

Uploading of single file.

Elements:

Element	Description
`filename`	Absolute path to source local file (in `value` attribute)
`destination`	Absolute path to destination remote file (in `value` attribute)2

Example:

<upload>
  <filename value="d:\www\about.htm" />
  <destination value="/home/martin/public_html/about.html" />
  <result success="true" />
</upload>

Associated script commands: keepuptodate, put, synchronize remote|both

touch

Changing of remote file timestamp.

Elements:

Element	Description
`filename`	Absolute path to remote file (in `value` attribute)
`modification`	Modification timestamp (in `value` attribute)1

Example:

<touch>
  <filename value="/home/martin/public_html/about.html" />
  <modification value="2008-12-28T11:22:19.000Z" />
  <result success="true" />
</touch>

Associated script commands: keepuptodate, put -preservetime, synchronize remote|both

Schema

XML schema for the XML log is available at: http://winscp.net/schema/session/1.0

Example

Note that the group elements will be included, if enabled only.

<?xml version="1.0" encoding="UTF-8"?>
<session xmlns="http://winscp.net/schema/session/1.0"
         name="martin@example.com" start="2009-03-02T19:34:57.734Z">
  <group name="put -preservetime -permissions=644 d:\www\about.htm" start="2012-01-04T14:28:45.393Z">
    <upload>
      <filename value="d:\www\about.htm" />
      <destination value="/home/martin/public_html/about.html" />
      <result success="true" />
    </upload>
    <touch>
      <filename value="/home/martin/public_html/about.html" />
      <modification value="2008-12-28T11:22:19.000Z" />
      <result success="true" />
    </touch>
    <chmod>
      <filename value="/home/martin/public_html/about.html" />
      <permissions value="rw-r--r--" />
      <result success="true" />
    </chmod>
  </group>
  <group name="rm about.bak" start="2012-01-04T14:28:47.892Z">
    <rm>
      <filename value="/home/martin/public_html/about.bak" />
      <result success="false">
        <message>No such file or directory.
Error code: 2
Error message from server: No such file
Request code: 13</message>
      </result>
    </rm>
    <failure>
      <message>No such file or directory.
Error code: 2
Error message from server: No such file
Request code: 13</message>
    </failure>
  </group>
</session>

Interpreting/Parsing

To parse the XML log, use any XML parser available.

If possible, using WinSCP .NET assembly is the preferred approach, which hides away the XML log file from your application.

If you want to parse the XML log yourself anyway, see following guides to learn how to do that in different development environments:

Guide to advanced scripting (Windows script host; Java or VB script);
Guide for using WinSCP from .NET (.NET; C# or VB.NET);
Guide to interpreting XML log for advanced scripting (.NET, C#).

All timestamps in XML log have XML dateTime type, where only YYYY-MM-DD"T"HH:MM:SS.NNN"Z" syntax is used.Back
File name may differ from name of source file.Back

XML Logging

Purpose

Using

Representing Operations in Log

Representing Results/Errors

Results/Errors of Operations

Results/Errors of Script

Grouping Operations for Commands

Elements

call

checksum

chmod

download

ls

mkdir

mv

rm

stat

upload

touch

Schema

Example

Interpreting/Parsing

Documentation

Support

Associations

Follow Us