Differences

This shows you the differences between two versions of the page.

--- util:sexyz [2010/02/24 15:20] – created digitalman
+++ util:sexyz [2023/12/22 12:16] (current) – [Overview] clarify native means 32-bit or 64-bit digital man
@@ Line 1: / Line 1: @@
 ====== SEXYZ ======
-FIXME
+Synchronet External X/Y/ZMODEM (SEXYZ) File Transfer Protocol Driver
+===== Overview =====
+SEXYZ was developed as a native (32-bit or 64-bit) TCP/socket-based replacement for the
+-bit DOS file transfer drivers (e.g. FDSZ, CE-XYZ, etc.) that we've been
+stuck with on 32-bit BBSes for FAR too long.
+While SEXYZ was designed with
+Synchronet BBSes in mind, it should also work with other 32-bit BBS packages
+that have the ability to pass socket descriptors to external file transfer
+protocol drivers.
+SEXYZ behaves much like DSZ/FDSZ and CE-XYZ:
+  * Familiar command-line syntax
+  * Supports the DSZLOG environment variable for result logging
+  * Supports batch transfer file lists
+SEXYZ has several advantages over legacy drivers like FDSZ and CE-XYZ:
+  * Faster (native, multi-threaded design)
+  * Socket-based (no need for FOSSIL drivers or virtual COM ports/UARTs)
+  * Multi-tasking friendly (does not needlessly consume CPU cycles)
+  * Supports long filenames (e.g. not just DOS "8.3" formatted names)
+  * Supports YMODEM-G and XMODEM-G (FDSZ does not)
+  * Handles Telnet IAC escaping and option negotiations (optionally)
+  * Transfers files over fast connections (e.g. 100KB/sec) without issue
+  * Actively developed and supported
+  * Open source (at cvs.synchro.net)!
+===== Distribution =====
+SEXYZ is freeware, licensed under the GNU General Public License ([[http://www.fsf.org/licensing/licenses/gpl.txt|GPL]]) with portions licensed under the GNU Lesser General Public License ([[http://www.fsf.org/licensing/licenses/lgpl.txt|LGPL]]).
+You can find the current source code (in C) in the Synchronet [[dev:CVS]] repository at ''cvs.synchro.net''.
+The latest and greatest build will be included in Synchronet-Win32 releases.
+You should be able to find/download the latest general release of SEXYZ-Win32
+(''sexyzNNN.zip'') at one or all of the following locations:
+  * http://www.synchro.net
+  * ftp://ftp.synchro.net
+  * ftp://vert.synchro.net
+  * telnet://vert.synchro.net
+SEXYZ can also be built from the C source code for use (natively) on Linux and other Unix variants (e.g. FreeBSD).
+For a client implementation of SEXYZ, use the SyncTerm Telnet/RLogin/SSH
+terminal program (http://syncterm.net/), available for many platforms,
+including Win32, *nix, and Mac OS-X.
+===== Command-line Syntax =====
+Just running "sexyz" by itself will display the supported command-line usage
+(options and commands):
+<code>
+usage: sexyz <socket> [-opts] <cmd> [file | path | @list]
+socket = TCP socket descriptor (leave blank for stdio mode)
+opts   = -y  allow overwriting of existing files when receiving
+         -k  enable X/YMODEM-1K send mode
+         -c  enable XMODEM-CRC receive mode
+         -g  enable X/YMODEM-G receive mode (no error recovery)
+         -o  disable ZMODEM CRC-32 mode (use CRC-16)
+         -s  use segmented ZMODEM (disable streaming)
+         -2  set maximum ZMODEM block size to 2K
+         -4  set maximum ZMODEM block size to 4K
+         -8  set maximum ZMODEM block size to 8K (ZedZap)
+         -w# set maximum ZMODEM transmit window size (default=0, unlimited)
+         -m# set maximum receive file size to # bytes (default=0, unlimited)
+         -l  lowercase received filenames
+         -!  to pause after abnormal exit (error)
+         -telnet to enable Telnet mode (the default except in stdio mode)
+         -rlogin or -ssh or -raw to disable Telnet mode
+cmd    = v  to display detailed version information
+         sx to send XMODEM     rx to receive XMODEM
+         sX to send XMODEM-1K  rc to receive XMODEM-CRC
+         sy to send YMODEM     ry to receive YMODEM
+         sY to send YMODEM-1K  rg to receive YMODEM-G
+         sz to send ZMODEM     rz to receive ZMODEM
+file   = filename to send or receive
+path   = directory to receive files into
+list   = name of text file with list of filenames to send or receive
+</code>
+NOTE: SEXYZ actually supports either ''+//list//'' or ''@//list//'' syntax for specifying
+a file list on the command-line. If the list file doesn't exist, it'll
+treat the ''+'' or ''@'' as part of the filename to send or receive.
+==== RZ/SZ Style ====
+SEXYZ also supports "rz/sz style" command-line syntax for some commands.
+Examples:
+^rz/sz style     ^Operation ^Protocol ^Same As^
+|''sexyz -c rx'' |receive |XMODEM-CRC |''sexyz rc''|
+|''sexyz -k sx'' |send    |XMODEM-1K  |''sexyz sX''|
+|''sexyz rb''    |receive |YMODEM     |''sexyz ry''|
+|''sexyz -k sb'' |send    |YMODEM-1K  |''sexyz sY''|
+|''sexyz -g ry'' |receive |YMODEM-G   |''sexyz rg''|
+|''sexyz -g rx'' |receive |XMODEM-G   |            |
+===== Install =====
+Copy ''sexyz[.exe]'' into your Synchronet ''[[dir:exec]]'' directory, if it's not already. Installation for other uses/systems likely just means copying the executable file somewhere that may be invoked from the application or server as needed.
+===== Configure =====
+==== Synchronet ====
+In Synchronet v3.14+ SCFG:File Options->Transfer Protocols:
+<code>
+[File Transfer Protocol]
+: Mnemonic (Command Key)        X
+: Protocol Name                 XMODEM-Original (SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p rx %f
+: Download Command Line         %!sexyz%. %h -%p sx %f
+: Batch Upload Command Line
+: Batch Download Command Line
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+[File Transfer Protocol]
+: Mnemonic (Command Key)        1
+: Protocol Name                 XMODEM-1K/CRC (SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p rC %f
+: Download Command Line         %!sexyz%. %h -%p sX %f
+: Batch Upload Command Line
+: Batch Download Command Line
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+[File Transfer Protocol]
+: Mnemonic (Command Key)        Y
+: Protocol Name                 YMODEM (SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p ry %f
+: Download Command Line         %!sexyz%. %h -%p sY %f
+: Batch Upload Command Line     %!sexyz%. %h -%p ry %g
+: Batch Download Command Line   %!sexyz%. %h -%p sY @%f
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+[File Transfer Protocol]
+: Mnemonic (Command Key)        G
+: Protocol Name                 YMODEM-G (SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p rg %f
+: Download Command Line         %!sexyz%. %h -%p sY %f
+: Batch Upload Command Line     %!sexyz%. %h -%p rg %g
+: Batch Download Command Line   %!sexyz%. %h -%p sY @%f
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+[File Transfer Protocol]
+: Mnemonic (Command Key)        Z
+: Protocol Name                 ZMODEM (SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p rz %f
+: Download Command Line         %!sexyz%. %h -%p sz %f
+: Batch Upload Command Line     %!sexyz%. %h -%p rz %g
+: Batch Download Command Line   %!sexyz%. %h -%p sz @%f
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+</code>
+=== Optional/Advanced ===
+<code>
+[File Transfer Protocol]
+: Mnemonic (Command Key)        8
+: Protocol Name                 ZMODEM-8K (SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p rz %f
+: Download Command Line         %!sexyz%. %h -%p -8 sz %f
+: Batch Upload Command Line     %!sexyz%. %h -%p rz %g
+: Batch Download Command Line   %!sexyz%. %h -%p -8 sz @%f
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+[File Transfer Protocol]
+: Mnemonic (Command Key)        S
+: Protocol Name                 ZMODEM-Synchronous(SEXYZ)
+: Access Requirements
+: Upload Command Line           %!sexyz%. %h -%p rz %f
+: Download Command Line         %!sexyz%. %h -%p -s sz %f
+: Batch Upload Command Line     %!sexyz%. %h -%p rz %g
+: Batch Download Command Line   %!sexyz%. %h -%p -s sz @%f
+: Bi-dir Command Line
+: Native (32-bit) Executable    Yes
+: Supports DSZLOG               Yes
+: Socket I/O                    Yes
+</code>
+NOTE: It is suggested you remove existing FDSZ, CE-XYZ, or sz/rz transfer protocol entries as they are no longer needed.
+=== Synchronet for Unix ===
+Synchronet for Unix (prior to v3.14) did not support socket-based file
+transfer protocols, so SEXYZ is only currently supported on Synchronet for
+Unix (v3.13 and older) in "stdio" mode.
+You can use "stdio" mode in SEXYZ by removing '%h' (the socket descriptor)
+from the above command-lines. If you're using Synchronet for Unix v3.14 or
+later, socket I/O mode is preferred (do not use "stdio" mode).
+==== Mystic ====
+Example configuration for Mystic BBS v1.08-Win32
+(provided by Dream Master and Jack Phlash)
+<code>
+A. Active     : Yes
+B. HotKey     : Z
+C. Description: ZMODEM
+D. Batch      : No
+E. Send Cmd   : c:\mystic\prots\sexyz.exe %0 sz %3
+F. Receive Cmd: c:\mystic\prots\sexyz.exe %0 rz %3
+A. Active     : Yes
+B. HotKey     : Z
+C. Description: ZMODEM batch
+D. Batch      : Yes
+E. Send Cmd   : c:\mystic\prots\sexyz.exe %0 sz @%3
+F. Receive Cmd: c:\mystic\prots\sexyz.exe %0 rz %3
+</code>
+==== EleBBS ====
+Example configuration for EleBBS-Win32
+(provided by Mike Ehlert, aka pcm)
+<code>
+Name            ZMODEM (SEXYZ)
+Key             Z
+Ext ctl file    No
+Batch           Yes
+Status          Always available
+Log file        DSZ.LOG
+Control file    DSZ.CTL
+DL command line c:\bbs\sexyz.exe *W -quotes sz @DSZ.CTL
+UL command line c:\bbs\sexyz.exe *W -quotes rz
+DL ctl string   @
+UL ctl string   @
+DL log keyword  z
+UL log keyword  Z
+Log name word   10
+Log desc word   0
+</code>
+You will need to have the environment variable ''DSZLOG'' set to ''DSZ.LOG''.
+It should *not* have a path of course, so that it's created in the current
+node's directory.
+Once you define that under control panel > system > env variables > system
+variables, be sure to close the window running eleserv or telsrv and reopen
+it for the environment variable to become active.. Otherwise there will be
+no log of the transfer and EleBBS will assume it failed.
+Note: To support long filenames with EleBBS, you'll need Sexyz v1.74 or later
+and set ''Quotes=true'' in the ''[DSZLOG]'' section of your ''sexyz.ini'' file or use
+the secret ''-quotes'' command-line option.
+===== Optional Initialization File (sexyz.ini) =====
+If the file ''[[config:sexyz.ini]]'' exists in the same directory as the sexyz executable
+(e.g. ''C:\sbbs\exec\sexyz.ini''), it will be loaded and used to over-ride the
+default operating parameters shown below. Like all Synchronet .ini files,
+you can have a unique .ini file for different local systems by embedding
+the local hostname (sexyz[.host].ini) or platform (sexyz[.platform].ini)
+in the filename. The filenames are *not* case sensitive. Examples:
+  * ''C:\sbbs\exec\sexyz.dadscomputer.ini''
+  * ''C:\sbbs\exec\sexyz.win32.ini''
+  * ''/sbbs/exec/sexyz.linux.ini''
+Example .ini file (with default values given):
+<code ini>
+Telnet=TRUE                 ; set to FALSE to change the default mode
+LogLevel=INFO               ; set display/log output level
+SysLog=FALSE                ; log to syslog (*nix only)
+Debug=FALSE                 ; enable debug logging (overrides LogLevel)
+DebugTx=FALSE               ; debug transmitted characters
+DebugRx=FALSE               ; debug received characters
+DebugTelnet=FALSE           ; debug Telnet commands
+PauseOnExit=FALSE           ; wait for key-press on exit
+PauseOnAbend=FALSE          ; wait for key-press on abnormal exit
+OutbufSize=16384            ; bytes (between 1024 and 65536)
+OutbufHighwaterMark=1100    ; bytes before auto-flush
+OutbufDrainTimeout=10       ; milliseconds before auto-flush
+ProgressInterval=1          ; interval (in seconds) of progress display
+MaxFileSize=0               ; maximum receive file size in bytes (0=unlimited)
+[XMODEM]
+SendTimeout=10      ; seconds
+RecvTimeout=10      ; seconds
+ByteTimeout=3       ; seconds
+AckTimeout=10       ; seconds
+BlockSize=1024      ; 128 or 1024
+MaxBlockSize=1024   ; 128 or 1024
+MaxErrors=9
+G_Delay=1           ; millisecond yield between sent X/YMODEM-G blocks
+SendG=TRUE          ; Support G-mode for X/YMODEM sends
+SendCRC=TRUE        ; Support CRC-16 error detection for X/YMODEM sends
+[YMODEM]
+FallbackToXMODEM=0  ; Failed send attempts before falling back to XMODEM
+[ZMODEM]
+InitTimeout=10      ; seconds
+SendTimeout=15      ; seconds
+RecvTimeout=20      ; seconds
+CrcTimeout=60       ; seconds
+BlockSize=1024      ; 1024 is usually best to start with
+MaxBlockSize=1024   ; 1024 is "true" ZMODEM, 8192 for ZMODEM-8K (ZedZap)
+MaxErrors=9         ; maximum number of consecutive errors
+RecvBufSize=0       ; specify non-zero for segmented receives
+Streaming=TRUE      ; set to FALSE to disable streaming (segmented receives)
+CRC32=TRUE          ; set to FALSE to force CRC-16 instead
+FullDuplex=TRUE     ; set to FALSE to disable window support (on receive)
+EscapeTelnetIAC=TRUE    ; send ZDLE/ZRUB1 instead of 0xff with -telnet
+Escape8thBit=FALSE      ; ZDLE-escape all bytes with bit-7 set
+EscapeCtrlChars=FALSE   ; ZDLE-escape all control characters (< 20h)
+MaxWindowSize=0         ; Set to non-zero number of bytes to use window management
+TargetWindowSize=0      ; Set to a duration (e.g. in seconds) to enable auto-adjusting window size
+[DSZLOG]
+Path=true           ; include full path to filename in log
+Short=false         ; use Micros~1 short path/filename in log (Windows)
+Quotes=false        ; enclose filename in "quotes" (for EleBBS)
+[SOCKOPTS]
+</code>
+**Notes:**\\
+  * The defaults and ''sexyz.ini'' specified values can be over-ridden via command-line options.
+  * Older versions of SEXYZ did not support comments on some of the ''sexy.ini'' lines shown above.
+  * See ''[[dir:ctrl]]/[[config:sockopts.ini]]'' for the Socket Options that can be set in the ''[SOCKOPTS]'' section.
+  * Versions of SEXYZ prior to 3.0 recognized a global ''TCP_NODELAY'' key. Now that key, if it is to be set, must be in the optional ''[SOCKOPTS]'' section (for advanced uses only).
+===== Compatibility =====
+The XMODEM, YMODEM, and ZMODEM file transfers should be compatible with any
+terminal programs or remote protocol drivers that conform to the public
+specifications for these protocols written by Chuck Forsberg (XMODEM was
+actually written by Ward Christensen, but was extended by others and
+documented by our good friend, Chuck).
+SEXYZ supports the following protocols and their popular permutations:
+|XMODEM     |128-byte blocks, 8-bit checksum error detection|
+|XMODEM-CRC |128-byte blocks, 16-bit CRC error detection|
+|XMODEM-1K  |1024-byte blocks, 16-bit CRC error detection|
+|XMODEM-G   |1024-byte blocks, 16-bit CRC error detection, and streaming (no acknowledgements or error recovery) (a.k.a. QMODEM-G)|
+|YMODEM     |128-byte blocks, 16-bit CRC error detection, batch file transfers|
+|YMODEM-1K  |1024-byte blocks, 16-bit CRC error detection, batch file transfers|
+|YMODEM-G   |1024-byte blocks, 16-bit CRC error detection, batch file transfers and streaming (no acknowledgements or error recovery)|
+|ZMODEM     |1024-byte blocks, 16-bit or 32-bit CRC error detection, batch file transfers, resume, auto-download, and more|
+|ZMODEM-8K  |8192-byte blocks, 16-bit or 32-bit CRC error detection, batch file transfers, resume, auto-download, and more (a.k.a. ZedZap)|
+SEXYZ will automatically fall back from 1024-byte block XMODEM/YMODEM send
+mode to 128-byte block XMODEM/YMODEM send mode if the receiver does not appear
+to support 1024-byte blocks.
+SEXYZ also supports automatically falling back from XMODEM/YMODEM-CRC to
+XMODEM/YMODEM-Checksum mode when sending to a receiver that does not support
+CRC-16 error detection.
+SEXYZ for Win32 has been tested successfully with the following Telnet clients
+/terminal programs:
+==== ztelnet ====
+  * OS: Linux
+  * Version: 1.2.2
+  * URL: ftp://ibiblio.org/pub/Linux/system/network/telnet/
+  * Tested: ZMODEM uploads and downloads
+  * Failed: none
+==== HyperTerminal Private Edition ====
+  * By: Hilgraeve, Inc.
+  * OS: Win32
+  * Version: 6.3
+  * URL: http://www.hilgraeve.com/htpe/
+  * Tested: XMODEM (checksum and CRC), XMODEM-1K, YMODEM-1K, YMODEM-G and ZMODEM  both uploads and downloads
+  * Failed: ZMODEM uploads (CRC errors detected): appears to be the fault of HyperTerminal and can be reproduced with any protocol driver on the BBS/server side (even FDSZ)
+==== mTelnet ====
+  * By: enigma
+  * OS: Win32
+  * Version: 1.0 (beta 12)/w32
+  * URL: http://ozone.eesc.com
+  * Tested: ZMODEM uploads and downloads
+  * Failed: none
+==== NetRunner ====
+  * By: Mystic Software Development (James Coyle/g00r00)
+  * OS: Win32
+  * Version: 0.09
+  * URL: www.mysticbbs.com
+  * Tested: ZMODEM uploads and downloads
+  * Failed: ZMODEM uploads (CRC errors detected): appears to be the fault of NetRunner and can be reproduced with any protocol driver on the BBS/server side (FDSZ and CEXYZ both failed in the same manner)
+==== ZOC ====
+  * By: EmTec, Innovative Software, Markus Schmidt
+  * OS: Win32
+  * Version: 5.02
+  * URL: http://www.emtec.com
+  * Tested: XMODEM, YMODEM, ZMODEM uploads and downloads
+  * Failed: none
+===== ZMODEM Streaming =====
+The ZMODEM protocol supports multiple methods of data streaming and error recovery. SEXYZ supports the following ZMODEM streaming modes, in order of decreasing successful data transfer assurance:
+  * **Segmented**: a "block at a time" mode, each data subpacket acknowledged by the receiver (whom can request this mode). Can be enabled when sending via the ''-s'' option or by setting ''Streaming=false'' in ''sexyz.ini''.
+  * **Window Management**: limiting the amount of data "in-flight" between the sender and receiver using asynchronous status reporting by the receiver. Can be controlled when sending via the ''-w'' option or by setting ''MaxWindowSize'' (and optionally ''TargetWindowSize'') in ''sexyz.ini''.
+  * **Full Streaming**: the default, subject to large send-buffering on the sending side potentially resulting in failed error-recovery or completion-acknowledgment timeouts.
+//Window Management// mode was added in SEXYZ v3.0 to support very asymmetric send-operations where the sender is a modern system, potentially with multiple-megabyte send-buffers, sending to a receiver that can only consume data at a rate of 115200bps (about 10KBytes/second) or less.
+===== Support =====
+For technical support (including bug reports), see [[howto:support]] for details.
+When submitting problem/bug reports, please include the version output from
+the ''sexyz v'' command. We're also very interested in reports of compatibility
+(or incompatibility) with terminal programs or telnet clients.
+===== Credits =====
+  * The XMODEM (a.k.a. MODEM, MODEM2) protocol was originally created by Ward Christensen in 1977.
+  * The XMODEM-CRC protocol (XMODEM derivative using a 16-CRC for error detection rather than XMODEM's 8-bit checksum) was created by John Mahr.
+  * The YMODEM, YMODEM-G and ZMODEM protocols were created and documented by [[http://omen.com|Chuck Forsberg]]; YMODEM being primarily a set of enhancements to Ward's XMODEM and Mahr's XMODEM-CRC protocols.
+  * The X/YMODEM code used in SEXYZ was written by [[person:digital man|Rob Swindell]], migrated from the Synchronet Transfer Protocols (STP) program circa 1997.
+  * The Unix "stdio" mode support and other optimizations in SEXYZ were written by [[person:deuce|Stephen Hurd]] of Synchronix/FreeBSD Synchronet stardom and "scary code" infamy.
+  * The ZMODEM code in SEXYZ is based on zmtx/zmrx v1.02 (C) Mattheij Computer Service 1994 by Jacques Mattheij <jacquesm [at] hacktic [dot] nl>. Although SEXYZ's ZMODEM code no longer resembles zmtx/zmrx much, it served as a good starting point, and Jacques' version of Chuck's ''ZMODEM.DOC'' was very helpful!
+  * The 16-bit CRC table and calculation macro was (unwittingly) contributed by Mark G. Mendel and Stephen Satchell.
+  * The 32-bit CRC table and calculation macro was (unwittingly) contributed by Gary S. Brown.
+  * SEXYZ includes portions of the Synchronet project (e.g. XPDEV) which are licensed under the GNU Lesser General Public License ([[http://www.fsf.org/licensing/licenses/lgpl.txt|LGPL]]).
 ===== See Also =====
+  * [[:ref:ZMODEM]]
   * [[:util:|Utilities]]
+{{tag>xmodem ymodem zmodem protocol}}

Trace:

Differences

Navigation

Search

Toolbox