SSH FTP Server command reference

Note: This section applies to the Cleo Harmony and Cleo VLTrader applications only.

The SSH FTP Server allows users to log into the VersaLexCleo HarmonyCleo VLTraderCleo LexiCom application and store and retrieve files using standard SSH FTP (Secure Shell File Transfer Protocol) commands. A full description of the SSH FTP commands can be found in the Internet-Draft draft-ietf-secsh-filexfer-02.txt specification.

The following SSH FTP packet types are accepted and processed by the VersaLexCleo HarmonyCleo VLTraderCleo LexiCom FTP server. The id field of each request or response has been omitted in the following descriptions. See SSH FTP file attributes for information about the <ATTRS attrs> parameter used in some of the commands.


Command	Description
Requests from the Client to the SSH FTP Server
`SSH_FXP_INIT` `<uint32 version>` `<optional extension data>`	Sent by the client when the transfer protocol starts. The client must be capable of supporting version 3 of the SSH FTP protocol. The server responds with a `SSH_FXP_VERSION` packet.
`SSH_FXP_VERSION` `<uint32 version>` `<optional extension data>`	Response to the SSH_FXP_INIT request.
`SSH_FXP_OPEN` `<string filename>` `<uint32 pflags>` `<ATTRS attrs>`	Files are opened or created when the client sends this message where filename field specifies the file name. The `pflags` field is a bitmask. The bits are defined as follows: `SSH_FXF_READ 0x00000001` `SSH_FXF_WRITE 0x00000002` `SSH_FXF_APPEND 0x00000004` `SSH_FXF_CREAT 0x00000008` `SSH_FXF_TRUNC 0x00000010` `SSH_FXF_EXCL 0x00000020` These have the following meanings: `SSH_FXF_READ` - Open the file for reading. `SSH_FXF_WRITE` - Open the file for writing. If both this and `SSH_FXF_READ` are specified, the file is opened for both reading and writing. `SSH_FXF_APPEND` - Force all writes to append data at the end of the file. `SSH_FXF_CREAT` - If this flag is specified, then a new file will be created if one does not already exist (if O_TRUNC is specified, the new file will be truncated to zero length if it previously exists). `SSH_FXF_TRUNC` - Forces an existing file with the same name to be truncated to zero length when creating a file by specifying `SSH_FXF_CREAT`. `SSH_FXF_CREAT` must also be specified if this flag is used. `SSH_FXF_EXCL` - Causes the request to fail if the named file already exists. `SSH_FXF_CREAT` must also be specified if this flag is used. The server response to this message will be either `SSH_FXP_HANDLE` (if successful) or `SSH_FXP_STATUS` (if the operation fails).
`SSH_FXP_CLOSE` `<string handle>`	A file is closed when the client sends this request. The server response to this request will be a `SSH_FXP_STATUS` message. The handle parameter is a handle previously returned in response to a `SSH_FXP_OPEN` or `SSH_FXP_OPENDIR`.
`SSH_FXP_READ` `<string handle>` `<uint64 offset>` `<uint32 len>`	Once a file has been opened, it can be read using the `SSH_FXP_READ` message. Only sequential offsets are supported, and repositioning within an open file is not allowed. In response to this request, the server will read as many bytes as it can from the file (up to 'len'), and return them in a `SSH_FXP_DATA` message. If an error occurs or EOF is encountered before reading any data, the server will respond with `SSH_FXP_STATUS`.
`SSH_FXP_WRITE` `<string handle>` `<uint64 offset>` `<uint32 len>` `<string data>`	When a file has been opened for writing, it can be written using the `SSH_FXP_WRITE` message. Only sequential offsets are supported and repositioning within an open file is not allowed. The server responds to a write request with a `SSH_FXP_STATUS` message.
`SSH_FXP_LSTAT` `<string path>`	Used to retrieve the attributes for a named file (identified by the 'path') while not following symbolic links. The server responds to this request with either `SSH_FXP_ATTRS` or `SSH_FXP_STATUS`.
`SSH_FXP_FSTAT` `<string path>`	`SSH_FXP_FSTAT` returns status information for an open file (identified by the file handle). The server responds to this request with `SSH_FXP_ATTRS` or `SSH_FXP_STATUS`.
`SSH_FXP_SETSTAT` `<string path>` `<ATTRS attrs>`	File attributes may be modified using the `SSH_FXP_SETSTAT` request where `path` specifies the file system object (for example, file or directory) whose attributes are to be modified, and `attrs` specifies the modifications to be made to its attributes. The server responds to this request with a `SSH_FXP_STATUS` message.
`SSH_FXP_FSETSTAT` `<string handle>` `<ATTRS attrs>`	File attributes on an open file may be modified using the `SSH_FXP_FSETSTAT` request where `handle` (must be returned by `SSH_FXP_OPEN`) identifies the file whose attributes are to be modified, and 'attrs' specifies the modifications to be made to its attributes. The server responds to this request with a `SSH_FXP_STATUS` message.
`SSH_FXP_OPENDIR` `<string path>`	The `SSH_FXP_OPENDIR` opens a directory for reading where `path` is the path name of the directory to be listed (without any trailing slash). The server will respond to this request with either a `SSH_FXP_HANDLE` or a `SSH_FXP_STATUS` message.
`SSH_FXP_READDIR` `<string handle>`	Once the directory has been successfully opened, files (and directories) contained in it can be listed using `SSH_FXP_READDIR` requests. The server responds to this request with either a `SSH_FXP_NAME` or a `SSH_FXP_STATUS` message.
`SSH_FXP_REMOVE` `<string filename>`	Files can be removed using the `SSH_FXP_REMOVE` message where `filename` is the name of the file to be removed. The Server responds with a `SSH_FXP_STATUS` message.
`SSH_FXP_MKDIR` `<string path>` `<ATTRS attrs>`	New directories can be created using the `SSH_FXP_MKDIR` request where `path` and `attrs` specify the directory name and attributes. The server will respond to this request with a `SSH_FXP_STATUS` message.
`SSH_FXP_RMDIR` `<string path>`	Directories can be removed using the `SSH_FXP_RMDIR` request where `path` specifies the directory to be removed. The server responds to this request with a `SSH_FXP_STATUS` message.
`SSH_FXP_REALPATH` `<string path>`	The `SSH_FXP_REALPATH` request can be used to have the server canonicalize any given path name to an absolute path. The server will respond with a `SSH_FXP_NAME` packet containing only one name and a dummy attributes value. The name is the returned packet will be in canonical form. If an error occurs, the server may also respond with `SSH_FXP_STATUS`.
`SSH_FXP_STAT` `<string path>`	Used to retrieve the attributes for a named file identified by the `path`. `SSH_FXP_STAT` and `SSH_FXP_LSTAT` only differ in that `SSH_FXP_STAT` follows symbolic links on the server. The server responds to this request with either `SSH_FXP_ATTRS` or `SSH_FXP_STATUS`.
`SSH_FXP_RENAME` `<string oldpath>` `<string newpath>`	Files (and directories) can be renamed using the `SSH_FXP_RENAME` message where `oldpath` is the name of an existing file or directory, and `newpath` is the new name for the file or directory. The server will respond to this request with a `SSH_FXP_STATUS` message.
`SSH_FXP_READLINK` `<string path>`	The server does not support reading symbolic links. The server will respond with a `SSH_FXP_STATUS` error message.
`SSH_FXP_SYMLINK` `<string linkpath>` `<string targetpath>`	The server does not support creating symbolic links. The server will respond with a `SSH_FXP_STATUS` error message.
Responses from the SSH FTP Server to Client
`SSH_FXP_VERSION` `<uint32 version>` `<optional extension data>`	Response to the `SSH_FXP_INIT` request. The server will respond supplying the lowest of its own (3) and the client's version number.
`SSH_FXP_STATUS` `<uint32 status>` `<string error>` `<string language>`	`SSH_FXP_STATUS` response is returned by the server in response to a client request where `status` indicates the result of the requested operation. The value `SSH_FX_OK` indicates success, and all other values indicate failure. `SSH_FX_OK` -Indicates successful completion of the operation. `SSH_FX_EOF` - indicates end-of-file condition; for `SSH_FX_READ` it means that no more data is available in the file, and for `SSH_FX_READDIR` it indicates that no more files are contained in the directory. `SSH_FX_NO_SUCH_FILE` - is returned when a reference is made to a file that should exist but does not. `SSH_FX_PERMISSION_DENIED` - is returned when the authenticated user does not have sufficient permissions to perform the operation. `SSH_FX_FAILURE` - is a generic catch-all error message; it should be returned if an error occurs for which there is no more specific error code defined. `SSH_FX_BAD_MESSAGE` - may be returned if a badly formatted packet or protocol incompatibility is detected. `SSH_FX_NO_CONNECTION` - is a pseudo-error that indicates the client has no connection to the server (it can only be generated locally by the client, and must not be returned by servers). `SSH_FX_CONNECTION_LOST` - is a pseudo-error that indicates the connection to the server has been lost (it can only be generated locally by the client, and must not be returned by servers). `SSH_FX_OP_UNSUPPORTED` - indicates that an attempt was made to perform an operation not supported for the server (it could be generated locally by the client if, for example, the version number exchange indicates that a required feature is not supported by the server, or it may be returned by the server if the server does not implement an operation).
`SSH_FXP_HANDLE` `<string handle>`	`SSH_FXP_HANDLE` is the server response to an `SSH_FXP_OPEN` or `SSH_FXP_OPENDIR` where `handle` is an arbitrary string that identifies an open file or directory on the server. The handle is opaque to the client; the client must not attempt to interpret or modify it in any way.
`SSH_FXP_DATA` `<string data>`	`SSH_FXP_DATA` is the server response to an `SSH_FXP_READ` where `data` is an arbitrary byte string containing the requested data. The data string may be at most the number of bytes requested in a `SSH_FXP_READ` request, but may also be shorter if end of file is reached or if the read is from something other than a regular file.
`SSH_FXP_NAME` `<uint32 count>` repeats count times: `<string filename>` `<string longname>` `<ATTRS attrs>`	`count` is the number of names returned in this response, and the remaining fields repeat `count` times (so that all three fields are first included for the first file, then for the second file, and so on). In the repeated `SSH_FXP_ NAME`is the server response to either a `SSH_FXP_READDIR` or `SSH_FXP_REALPATH` message where `filename` is a file name being returned (for `SSH_FXP_READDIR`, it will be a relative name within the directory, without any path components; for `SSH_FXP_REALPATH` it will be an absolute path name), `longname` is an expanded format for the file name, similar to what is returned by ls -l on Unix systems.
SSH_FXP_ATTRS `<ATTRS attrs>`	SSH_FXP_ATTRS is the server response for returning file attributes.

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom also supports HTTP PUT, GET, and DELETE methods for sending payload, receiving directory listings and payload, and deleting payload respectively, but the POST methods are recommended. Following are captures of example HTTP requests and responses demonstrating the above methods. While the examples below only show parameters on the POST line, VersaLexCleo HarmonyCleo VLTraderCleo LexiCom does accept requests using the application/x-www-form-urlencoded and multipart/form-data Content-types.

Client initial connect request without authorization

POST /server?request=connect HTTP/1.1
Host: test.cleo.com:5080
Connection: Keep-Alive, TE
TE: trailers, deflate, gzip, compress
User-Agent: RPT-HTTPClient/0.3-3I (Windows XP)
Content-length: 0

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom response (unauthorized; both basic and digest Authentication is enabled)

HTTP/1.1 401 Unauthorized
Server: Cleo VLTrader/3.5 (Windows 2000)
Date: Tue, 22 May 2007 17:04:13 GMT
WWW-Authenticate: Basic realm="Cleo VLTrader"
WWW-Authenticate: Digest realm="Cleo VLTrader",domain="/server",qop="auth",nonce="0qenmpn44",opaque="4b4c37373332"
Connection: close
Content-Type: text/html
Content-Length: 80
<html><head><title> Unauthorized</title></head><body> Unauthorized</body></html>

Client connect request with digest authorization

POST /server?request=connect HTTP/1.1
Host: test.cleo.com:5080
Connection: TE
TE: trailers, deflate, gzip, compressUser-Agent: RPT-HTTPClient/0.3-3I (Windows XP)
Authorization: Digest realm="Cleo VLTrader",username="cleo",uri="/server%3Frequest=connect",nonce="0qenmpn44",response="b4f7542bdedce937de6aa93078fcdf17",opaque="4b4c37373332",cnonce="f5f20437b69ca661e4aedfedb54f5c32",qop="auth",nc="00000001"
Content-length: 0

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom response (authentication successful)

HTTP/1.1 200 OK
Server: Cleo VLTrader/3.5 (Windows 2000)
Date: Tue, 22 May 2007 17:04:18 GMT
Content-Length: 0
Set-cookie: jSessionId=3513ld61kg8bt; path=/
Connection: keep-alive

Client send (upload) request

POST /server?request=send&directory=inbox%2F HTTP/1.1
Host: test.cleo.com:5080
Connection: TE
TE: trailers, deflate, gzip, compress
User-Agent: RPT-HTTPClient/0.3-3I (Windows XP)
Cookie: jSessionId=3513ld61kg8bt
Cookie2: $Version="1"
Authorization: Digest realm="Cleo VLTrader",username="cleo",uri=...
Content-type: application/octet-stream; name="test.edi"
Content-length: 1533
...payload...

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom response (send successful)

HTTP/1.1 200 OK
Server: Cleo VLTrader/3.5 (Windows 2000)
Date: Tue, 22 May 2007 17:19:59 GMT
Content-Type: text/html
Content-Length: 84
Connection: keep-alive
<html><head><title>OK</title></head><body>File successfully uploaded.</body></html>

Client list request

POST /server?request=list&directory=outbox%2Fpayload%2F HTTP/1.1
Host: test.cleo.com:5080
Connection: TE
TE: trailers, deflate, gzip, compress
User-Agent: RPT-HTTPClient/0.3-3I (Windows XP)
Cookie: jSessionId=3513ld61kg8bt
Cookie2: $Version="1"
Authorization: Digest realm="Cleo VLTrader",username="cleo",uri=...
Content-length: 0

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom response (listing successful)

HTTP/1.1 200 OK
Server: Cleo VLTrader/3.5 (Windows 2000)
Date: Tue, 22 May 2007 17:04:18 GMT
Content-Type: text/html
Content-Length: 402
Connection: keep-alive
<head><title>'cleo' mailbox</title></head><body><pre><H2>Download</H2>Server directory: outbox/payload/<hr>
2007/05/03 08:43:17   1.497kB <A HREF="/server/outbox/payload/test.edi" >test.edi</A><br>
2007/05/22 08:32:46   4.491kB <A HREF="/server/outbox/payload/test2.edi" >test2.edi</A><br>
2007/05/22 08:33:28  28.444kB <A HREF="/server/outbox/payload/test3.edi" >test3.edi</A><br><hr></pre></body>

Client receive (download) request

POST /server?request=receive&directory=outbox%2Fpayload&filename=test.edi HTTP/1.1
Host: test.cleo.com:5080
Connection: TE
TE: trailers, deflate, gzip, compress
User-Agent: RPT-HTTPClient/0.3-3I (Windows XP)
Cookie: jSessionId=3513ld61kg8bt
Cookie2: $Version="1"
Authorization: Digest realm="Cleo VLTrader",username="cleo",uri=...
Content-length: 0

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom response (receive successful)

HTTP/1.1 200 OK
Server: Cleo VLTrader/3.5 (Windows 2000)
Date: Tue, 22 May 2007 17:25:57 GMT
Content-Description: test.edi
Content-Disposition: attachment; filename="test.edi"
Transfer-Encoding: chunked
Content-Type: application/edi-x12; name="test.edi"
Connection: keep-alive
...chunked payload...

Client delete request

POST /server?request=delete&directory=outbox%2Fpayload&filename=test.edi HTTP/1.1
Host: test.cleo.com:5080
Connection: TE
TE: trailers, deflate, gzip, compress
User-Agent: RPT-HTTPClient/0.3-3I (Windows XP)
Cookie: jSessionId=3513ld61kg8bt
Cookie2: $Version="1"
Authorization: Digest realm="Cleo VLTrader",username="cleo",uri=...
Content-length: 0

VersaLexCleo HarmonyCleo VLTraderCleo LexiCom response (delete successful)

HTTP/1.1 200 OK
Server: Cleo VLTrader/3.5 (Windows 2000)
Date: Tue, 22 May 2007 17:25:58 GMT
Content-Length: 0
Connection: keep-alive

A web browser can also be used by a trading partner to manually trade with VerasLex's HTTP server. A trading partner would use the VersaLexCleo HarmonyCleo VLTraderCleo LexiCom address and HTTP server resource path to start, for example, https://test.cleo.com:6080/server:

After logging in, a simple web page is displayed to allow uploading and downloading of files.

Note: For information about a more robust web portal interface, see Configuring VLPortal Web Browser service.