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.

Advertisement

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.

The XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not. See below.

Using

XML logging is mostly useful with logging to file only. 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.

Advertisement

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 of Operations

First, note that the XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not.

When checking for outcome of batch execution, you need check positively for presence of operations you have executed. Absence of errors does not indicate success. Note, when using scripting, you should check WinSCP exit code for detection of errors.

XML log may not include some errors, even if they occur, for two reasons:

  • The operation that failed does not have corresponding log element (see above).
  • The error is not associated with particular physical operation. Simple example is authentication failure. More treacherous example is failure to list remote directory, to find list of files it contains, while downloading the directory. This error occurs during download operation, which is logged. But as download of individual files is logged only, the error is not associated with download of any particular file. So it will be absent from the XML log.

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.

Result of an 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>

Elements

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

Advertisement

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

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

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

Advertisement

Example:

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

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" />
</upload>

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)

Advertisement

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" />
</upload>

Advertisement

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, rm, rmdir, synchronize local|both -delete

upload

Uploading of single file.

Advertisement

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

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

Last modified: by martin