====== File Options ======
The global configuration settings for file transfers are set in [[util:SCFG]]->File Options.

The values shown in the screens on this page are the **stock defaults** — what a
brand new Synchronet installation starts with, before any sysop customization.

  ╔════════════════════════════════════════════════════════════════════════╗
  ║                             File Options                               ║
  ╠════════════════════════════════════════════════════════════════════════╣
  ║ │Minimum Free Disk Space          1G bytes                             ║
  ║ │Max Files in Batch UL Queue      25                                   ║
  ║ │Max Files in Batch DL Queue      100                                  ║
  ║ │Max Users in User Transfers      5                                    ║
  ║ │Default Credit on Upload         100%                                 ║
  ║ │Default Credit on Download       90%                                  ║
  ║ │Leech Protocol Detection         <disabled>                           ║
  ║ │Allowed Filename Length          64 characters                        ║
  ║ │Allowed Filename Characters      Most ASCII, Including Spaces         ║
  ║ │Supported Archive Formats        zip, 7z, tgz                         ║
  ║ │Viewable Files...                                                     ║
  ║ │Testable Files...                                                     ║
  ║ │Download Events...                                                    ║
  ║ │Extractable Files...                                                  ║
  ║ │Compressible Files...                                                 ║
  ║ │Transfer Protocols...                                                 ║
  ╚════════════════════════════════════════════════════════════════════════╝

^ Option Name                    ^ Description ^
| Minimum Free Disk Space        | Minimum free space that must remain on the file directory's filesystem to allow user uploads (e.g. ''1G'', ''100M''). Default: ''1G''. |
| Max Files in Batch UL Queue    | Maximum number of files that can be placed in the batch upload queue. Default: ''25''. |
| Max Files in Batch DL Queue    | Maximum number of files that can be placed in the batch download queue. Default: ''100''. |
| Max Users in User Transfers    | Maximum number of destination users in user-to-user file uploads. Default: ''5''. |
| Default Credit on Upload       | Default percentage of credits given to uploaders, used as the default for newly created file directories. Default: ''100%''. |
| Default Credit on Download     | Default percentage of credits given to the original uploader when their file is downloaded by another user, used as the default for newly created file directories. Default: ''90%''. |
| Leech Protocol Detection       | If enabled, determines sensitivity to counting/logging potential leech downloads (see [[#leech_protocol_detection|below]]). Default: disabled. |
| Allowed Filename Length        | Maximum uploaded filename length allowed (in characters). Default: ''64''. \\ \\ Only 64 characters of filenames are indexed (searchable) and sometimes (depending on the terminal) only 64 or fewer characters of a filename may be displayed to a user. For these reasons, 64 characters is a reasonable maximum filename length to enforce (and thus, the default). \\ \\ The absolute maximum filename length supported is 65535 characters. |
| Allowed Filename Characters    | Allowed Characters in Uploaded Filenames: \\ - Safest Subset Only (A-Z, a-z, 0-9, -, _, and .) \\ - Most ASCII Characters, Excluding Spaces \\ - Most ASCII Characters, Including Spaces \\ - Most CP437 Characters, Excluding Spaces \\ - Most CP437 Characters, Including Spaces \\ \\ Default: //Most ASCII Characters, Including Spaces//. \\ \\ Whichever setting is chosen, some filenames are //always// disallowed (as are any filenames matching your ''text/file.can'' file): those beginning with a dash, beginning or ending with a space or a period, containing consecutive periods, containing control characters (ASCII 0-31 and 127), or containing any of ''%%\/|<>:";,%?*%%''. \\ \\ As of v3.22, an uploaded filename containing a dollar-sign (''%%$%%'') or a back-tick (''%%`%%'') is also rejected. A command shell expands both characters even inside the double-quotes Synchronet places around a filename it passes to an external program (a [[#viewable_file_types|viewer]], [[#testable_file_types|test]], or [[#download_events|download event]] command), so no amount of quoting makes them safe. Neither character is special to ''cmd.exe'', but file bases are commonly shared between Windows and Unix-like systems, so the restriction applies on every platform. \\ \\ This one is narrower than the list above: it rejects the //upload//, quietly, rather than logging a suspicious-filename attempt, and it is not applied to names already stored in your file base or to names arriving over FTP, in message attachments, or in QWK packets — so an existing legal filename doesn't become an attack report. |
| Supported Archive Formats      | List of archive file types (extensions/suffixes, without the leading ''.'') that libarchive should use when creating QWK/REP packets and temporary archives of files for users to download. \\ \\ Default: ''zip, 7z, tgz''. \\ \\ This list has no impact on the file types allowed to be uploaded into file areas, or on the ability to view, test, or extract archives of any other type. |
| Viewable Files...              | Sub-menu — see [[#viewable_file_types|Viewable File Types]]. |
| Testable Files...              | Sub-menu — see [[#testable_file_types|Testable File Types]]. |
| Download Events...             | Sub-menu — see [[#download_events|Download Events]]. |
| Extractable Files...           | Sub-menu — see [[#extractable_file_types|Extractable File Types]]. |
| Compressible Files...          | Sub-menu — see [[#compressible_file_types|Compressible File Types]]. |
| Transfer Protocols...          | Sub-menu — see [[#file_transfer_protocols|File Transfer Protocols]]. |

===== Leech Protocol Detection =====

This value is the sensitivity of the leech protocol detection feature of Synchronet. If the transfer is apparently unsuccessful, but the transfer time was at least this percentage of the estimated transfer time (estimated from the user's most recently measured transfer rate), then a leech protocol error is issued and the user's leech download counter is incremented. Setting this value to ''0'' disables leech protocol detection (the default). This option also allows you to set the minimum amount of elapsed transfer time (in seconds, default ''60'') to be considered for a possible leech download.

Leech protocol programs are file transfer programs (usually using ZMODEM technology) that attempt to "fool" the BBS into thinking the file was not successfully transferred, when in reality it was. This is accomplished by the transfer program requesting a reposition (ZRPOS) after the last successful block and then aborting (ZCAN). A file transferred in this manner will not be considered a successful transfer by Synchronet, but will be caught as a possible leech download and notify the sysop (if this option is used).

This feature is also useful for detecting the partial download of image (GIF) files. If you charge your users credits for downloads, this can be a very useful feature in detecting dishonest users. If the user accumulates a large number of leeches (as displayed in [[access:user_editor|User Edit]]) and the user never successfully downloads a file previously logged as a possible leech download, the user is probably trying to get something for nothing, though this is hard to prove without actually watching the file transfer in progress.

===== File Extensions and Matching =====

Five of the sub-menus below (//Viewable//, //Testable//, //Download Events//, //Extractable// and //Compressible//) are lists of //file types// paired with a [[config:cmdline|command line]]. They all match files the same way, and the rules are easy to get wrong:

  * **Do not include the leading period.** The extension is stored as ''ZIP'', not ''%%.ZIP%%''. Synchronet matches a file by building the file specification ''%%*.<extension>%%'' — so an entry of ''%%.ZIP%%'' becomes ''%%*..ZIP%%'' and will never match anything. SCFG's prompt reflects this: //File Extension (e.g. zip or *)//.
  * Matching is **case-insensitive**, so ''ZIP'' matches ''readme.zip'' and ''README.ZIP'' alike.
  * The ''%%*%%'' and ''%%?%%'' wildcards are allowed within the extension, e.g. ''%%Z?P%%''. An extension of ''%%*%%'' matches any file **that has an extension** — a filename with no period in it matches nothing.
  * Multi-part extensions work: an entry of ''%%TAR.GZ%%'' matches ''archive.tar.gz''.

Each entry also has an ''Access Requirements'' ([[access:requirements|ARS]]) string; entries whose ARS the user doesn't meet are skipped.

**How many entries run:** //Testable Files// and //Download Events// execute **every** matching entry, in list order. //Viewable Files//, //Extractable Files// and //Compressible Files// use only the **first** matching entry. Order your entries accordingly — put specific extensions above a catch-all ''%%*%%''.

===== Viewable File Types =====

A list of file types (extensions) whose content can be **viewed** on the [[server:terminal|Terminal Server]] through the execution of an external program or script. This is what a user gets from the //View// command in a file listing.

  ╔════════════════════════════════════════════╗
  ║            Viewable File Types             ║
  ╠════════════════════════════════════════════╣
  ║ │TXT             ?printfile %s             ║
  ║ │DIZ             ?printfile %s             ║
  ║ │DOC             ?printfile %s             ║
  ║ │ANS             ?printfile %s             ║
  ║ │ASC             ?printfile %s             ║
  ║ │RIP             ?printfile %s             ║
  ║ │NFO             ?printfile %s             ║
  ║ │FAQ             ?printfile %s             ║
  ║ │ICE             ?printfile %s             ║
  ║ │HTM             ?typehtml -color %s       ║
  ║ │SEQ             ?printfile %f P_WRAP 40   ║
  ║ │*               ?archive list %f          ║
  ║ │                                          ║
  ╚════════════════════════════════════════════╝

The stock list displays the common plain-text and ANSI file types with the ''printfile'' module, renders ''HTM'' files as text with ''typehtml'', and falls through to the ''archive'' module for everything else — which lists the contents of any archive format libarchive understands, without extracting it.

As of v3.22, the ''archive'' module falls back to the ''lsar'' command (from [[https://theunarchiver.com/command-line|The Unarchiver]]) for the formats libarchive can't read: ARC, ARJ, ZOO, LBR, StuffIt and other older archive types still found in file bases. There's nothing to configure — if ''lsar'' isn't installed and in the PATH of the account running Synchronet, those file types simply report that they can't be listed. On Linux and FreeBSD it's a package (see the [[install:nix:prerequisites|Unix/Linux prerequisites]]); on Windows, download the command-line tools from the same site and put ''lsar.exe'', along with the ''Foundation'' DLL shipped beside it, somewhere on the system PATH.

A listing is also remembered per file area once produced, so viewing the same archive again doesn't re-open it. The stored listing is discarded if the file's size or date changes.

Both ''%%%f%%'' and ''%%%s%%'' expand to the path of the file being viewed.

==== Viewable File Type ====

  ╔════════════════════════════════════════╗
  ║           Viewable File Type           ║
  ╠════════════════════════════════════════╣
  ║ │File Extension        TXT             ║
  ║ │Command Line          ?printfile %s   ║
  ║ │Native Executable     No              ║
  ║ │Access Requirements                   ║
  ╚════════════════════════════════════════╝

^ Option Name           ^ Description ^
| File Extension         | Suffix to match, //without// a leading period (e.g. ''ZIP''). See [[#file_extensions_and_matching|File Extensions and Matching]]. |
| Command Line           | The [[config:cmdline|command line]] to execute. Use ''%%%f%%'' or ''%%%s%%'' for the file's path. Standard prefixes apply (''?'' for a JavaScript module in [[dir:exec|exec]], ''%%*%%'' for JavaScript or Baja). |
| Native Executable      | ''Yes'' for native binaries; ''No'' for MS-DOS programs. The stock entries are JavaScript modules, for which this setting is not meaningful. |
| Access Requirements    | An [[access:requirements|ARS]] expression — only users matching it will see this view option for matching files. |

===== Testable File Types =====

A list of file types whose **upload** triggers a sysop-configured test command. The test must return error code ''0'' to mean "passed" — a non-zero exit code rejects the upload. Use this for virus scanning, archive integrity checks, or any sysop-side processing. Also known as an //upload processing event//.

  ╔═══════════════════════════════════════════════╗
  ║              Testable File Types              ║
  ╠═══════════════════════════════════════════════╣
  ║ │ZIP             %@unzip -tqq %f              ║
  ║ │ZIP             %@zip -z %f < %zzipmsg.txt   ║
  ║ │                                             ║
  ╚═══════════════════════════════════════════════╝

The two stock entries illustrate that **every** matching entry runs, in order: the first tests the uploaded ZIP's integrity, and the second — only reached if the first succeeded — stamps your ''[[dir:text|text]]/zipmsg.txt'' into the archive as its ZIP comment. ''%%%z%%'' is the [[dir:text|text directory]] and ''%%%@%%'' is the [[dir:exec|exec directory]] on Windows (and expands to nothing on Unix-like systems, so the program is found on the ''PATH'').

A test command can also **modify** the upload: it may rewrite ''sbbsfile.nam'' (filename) or ''sbbsfile.des'' (description) in the [[dir:node|node directory]] before Synchronet finalizes the upload.

==== Testable File Type ====

  ╔═══════════════════════════════════════════════════╗
  ║                 Testable File Type                ║
  ╠═══════════════════════════════════════════════════╣
  ║ │File Extension        ZIP                        ║
  ║ │Command Line          %@unzip -tqq %f            ║
  ║ │Native Executable     Yes                        ║
  ║ │Working String        Testing ZIP Integrity...   ║
  ║ │Access Requirements                              ║
  ╚═══════════════════════════════════════════════════╝

Same fields as [[#viewable_file_type|Viewable File Type]], plus:

^ Option Name      ^ Description ^
| Working String    | Optional message displayed to the user while the test command runs (e.g. //"Testing ZIP Integrity..."//). Leave blank for silent operation. |
| Command Line      | Here ''%%%f%%'' is the path to the uploaded file and ''%%%s%%'' is the path to the ''sbbsfile.des'' file (the file's description), //not// the file itself. |

===== Download Events =====

A list of file types that trigger a command line when a file is downloaded. The command runs **before** the file is sent, and its exit code is ignored — a download event cannot cancel a download. Use this for download notifications, statistics tracking, or preparing the file for transfer. Every matching entry runs, in list order.

**The stock list is empty:**

  ╔═══════════════════╗
  ║  Download Events  ║
  ╠═══════════════════╣
  ║ │                 ║
  ╚═══════════════════╝

==== Download Event ====

An example entry (nothing here is stock — ''dlnotify'' stands in for a module you supply):

  ╔══════════════════════════════════════════════╗
  ║                Download Event                ║
  ╠══════════════════════════════════════════════╣
  ║ │File Extension        ZIP                   ║
  ║ │Command Line          ?dlnotify %f          ║
  ║ │Native Executable     No                    ║
  ║ │Working String        Logging download...   ║
  ║ │Access Requirements                         ║
  ╚══════════════════════════════════════════════╝

Same fields as [[#testable_file_type|Testable File Type]], except that ''%%%f%%'' is the only useful specifier — ''%%%s%%'' is empty here.

===== Extractable File Types =====

External extraction methods, by file type. Synchronet extracts the [[#file_options|Supported Archive Formats]] itself (''zip'', ''7z'' and ''tgz'' by default, via libarchive) and needs **no** entry here for those. Add an entry only for archive types Synchronet can't decompress on its own.

These commands are used when Synchronet needs to open an archive it doesn't natively support: pulling ''FILE_ID.DIZ'' out of an uploaded archive for its description, and unpacking an uploaded QWK ''REP'' packet. Only the first matching entry is used.

**The stock list is empty:**

  ╔══════════════════════════╗
  ║  Extractable File Types  ║
  ╠══════════════════════════╣
  ║ │                        ║
  ╚══════════════════════════╝

==== Extractable File Type ====

An example entry (not stock — requires an ''unrar'' program you supply):

  ╔════════════════════════════════════════════╗
  ║           Extractable File Type            ║
  ╠════════════════════════════════════════════╣
  ║ │File Extension        RAR                 ║
  ║ │Command Line          %@unrar%. x %f %s   ║
  ║ │Native Executable     Yes                 ║
  ║ │Access Requirements                       ║
  ╚════════════════════════════════════════════╝

Same fields as [[#viewable_file_type|Viewable File Type]]. Here ''%%%f%%'' is the archive to extract //from// and ''%%%s%%'' is the file specification to extract, and the command runs with the node's temp directory as its destination.

===== Compressible File Types =====

External compression methods, by file type. Like //Extractable//, this **extends** Synchronet's built-in handling of the [[#file_options|Supported Archive Formats]] — add an entry only when a format Synchronet can't produce itself is required.

The extensions listed here are offered to users, alongside the Supported Archive Formats, as their //temp file archive type// — the format used to package QWK message packets and multi-file temporary downloads. Only the first matching entry is used.

**The stock list is empty:**

  ╔═══════════════════════════╗
  ║  Compressible File Types  ║
  ╠═══════════════════════════╣
  ║ │                         ║
  ╚═══════════════════════════╝

==== Compressible File Type ====

An example entry (not stock — requires a ''rar'' program you supply):

  ╔══════════════════════════════════════════╗
  ║          Compressible File Type          ║
  ╠══════════════════════════════════════════╣
  ║ │File Extension        RAR               ║
  ║ │Command Line          %@rar%. a %f %s   ║
  ║ │Native Executable     Yes               ║
  ║ │Access Requirements                     ║
  ╚══════════════════════════════════════════╝

Same fields as [[#viewable_file_type|Viewable File Type]]. Here ''%%%f%%'' is the archive to create and ''%%%s%%'' is the file specification to add to it.

===== File Transfer Protocols =====

A list of file transfer protocols available to users for upload and download. Every protocol is a program or script invoked through the command lines configured here — including the ones Synchronet ships with. The stock entries all drive [[util:sexyz|SEXYZ]], Synchronet's own [[ref:xmodem|XMODEM]] / [[ref:ymodem|YMODEM]] / [[ref:zmodem|ZMODEM]] transfer program.

  ╔═══════════════════════════╗
  ║  File Transfer Protocols  ║
  ╠═══════════════════════════╣
  ║ │X  XMODEM-Original       ║
  ║ │1  XMODEM-1K/CRC         ║
  ║ │Y  YMODEM                ║
  ║ │G  YMODEM-G              ║
  ║ │Z  ZMODEM                ║
  ║ │L  Local Copy            ║
  ║ │                         ║
  ╚═══════════════════════════╝

The stock command lines, as configured in each entry:

^ Key ^ Protocol Name ^ Upload ^ Download ^ Batch Upload ^ Batch Download ^
| ''X'' | XMODEM-Original | ''%%%!sexyz%. %h -%p rx %f%%'' | ''%%%!sexyz%. %h -%p sx %f%%'' | //(none)// | //(none)// |
| ''1'' | XMODEM-1K/CRC | ''%%%!sexyz%. %h -%p rC %f%%'' | ''%%%!sexyz%. %h -%p sX %f%%'' | //(none)// | //(none)// |
| ''Y'' | YMODEM | ''%%%!sexyz%. %h -%p ry %f%%'' | ''%%%!sexyz%. %h -%p sY %f%%'' | ''%%%!sexyz%. %h -%p ry %g%%'' | ''%%%!sexyz%. %h -%p sY @%f%%'' |
| ''G'' | YMODEM-G | ''%%%!sexyz %h -%p rg %f%%'' | ''%%%!sexyz %h -%p sY %f%%'' | ''%%%!sexyz %h -%p rg %g%%'' | ''%%%!sexyz %h -%p sY @%f%%'' |
| ''Z'' | ZMODEM | ''%%%!sexyz%. %h -%p rz %f%%'' | ''%%%!sexyz%. %h -%p sz %f%%'' | ''%%%!sexyz%. %h -%p rz %g%%'' | ''%%%!sexyz%. %h -%p sz @%f%%'' |
| ''L'' | Local Copy | ''%%?localcopy send %f%%'' | ''%%?localcopy recv %f%%'' | ''%%?localcopy send %g%%'' | ''%%?localcopy recv %s%%'' |

All five SEXYZ entries have //Native Executable//, //Supports DSZLOG// and //Socket I/O// set to ''Yes''. //Local Copy// has all three set to ''No'' and an //Access Requirements// of ''SYSOP'' — it copies files between the local filesystem and the file area, prompting at the server console, so it is not offered to remote users.

XMODEM has no batch capability, so its two batch command lines are left blank — that is how a protocol is kept out of the batch transfer menus.

The command-line specifiers used by these entries:

^ Specifier ^ Meaning ^
| ''%%%!%%'' | The Synchronet [[dir:exec|exec directory]]. |
| ''%%%.%%'' | The executable file extension (''.exe'' on Windows, nothing on Unix-like systems). |
| ''%%%h%%'' | The TCP socket descriptor (handle) of the user's connection — SEXYZ transfers over it directly. |
| ''%%%p%%'' | The connection type (''telnet'', ''rlogin'', ''ssh'' or ''raw''), which SEXYZ accepts as an option to enable or disable Telnet escaping. |
| ''%%%f%%'' | The path of the file to send or receive. For a batch transfer it is the path of a list-file that Synchronet writes, hence the ''%%@%f%%'' form SEXYZ uses to read filenames from it. |
| ''%%%s%%'' | On a batch download only: every queued file's full path, space-separated, on the command line itself. Truncated at 511 characters, so a list-file (''%%@%f%%'') is the safer choice for a large batch. |
| ''%%%g%%'' | The Synchronet temp directory — where a batch upload's files are received. |

See [[config:cmdline|command line]] for the full list.

==== File Transfer Protocol ====

  ╔══════════════════════════════════════════════════════════╗
  ║                  File Transfer Protocol                  ║
  ╠══════════════════════════════════════════════════════════╣
  ║ │Mnemonic (Command Key)        Z                         ║
  ║ │Protocol Name                 ZMODEM                    ║
  ║ │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   ║
  ║ │Native Executable             Yes                       ║
  ║ │Supports DSZLOG               Yes                       ║
  ║ │Socket I/O                    Yes                       ║
  ╚══════════════════════════════════════════════════════════╝

^ Option Name                  ^ Description ^
| Mnemonic (Command Key)        | The single keystroke users press at the protocol-selection prompt to pick this protocol (e.g. ''Z'' for ZMODEM). It is forced to upper case. Uniqueness isn't enforced, but if two entries share a key only the first one can ever be selected. |
| Protocol Name                 | Display name shown in the protocol-selection menu. |
| Access Requirements           | An [[access:requirements|ARS]] expression — only users matching it will see this protocol as an option. |
| Upload Command Line           | [[config:cmdline|Command line]] for **single-file uploads**. ''%%%f%%'' is the path of the file being received. Leave blank to keep this protocol out of the upload menu. |
| Download Command Line         | Command line for **single-file downloads**. ''%%%f%%'' is the path of the file being sent. |
| Batch Upload Command Line     | Command line for **batch (multi-file) uploads**. ''%%%f%%'' is the path of a list-file naming the files the user has queued and ''%%%g%%'' is the directory to receive them into. Leave blank if the protocol doesn't support batch uploads. |
| Batch Download Command Line   | Command line for **batch downloads**. ''%%%f%%'' is the path of a list-file containing the full path of each queued file, one per line — this is what the stock entries pass to SEXYZ as ''%%@%f%%''. ''%%%s%%'' is the alternative: it expands to all of those paths on the command line itself, separated by spaces, each one double-quoted if it contains a space. \\ \\ Prefer the list-file. The expanded command line is truncated at 511 characters on every platform, so ''%%%s%%'' silently drops files from a large batch. |
| Native Executable             | ''Yes'' for native binaries; ''No'' for MS-DOS programs. |
| Supports DSZLOG               | If ''Yes'', the program writes a DSZ-compatible transfer log (named by the ''DSZLOG'' environment variable, which Synchronet sets to ''PROTOCOL.LOG'' in the [[dir:node|node directory]]), and Synchronet reads that log to decide whether each file really transferred. If ''No'', the program's exit code is used instead. |
| Socket I/O                    | (*nix only) If ''Yes'', the protocol is handed the user's TCP socket (via ''%%%h%%'') and does its own I/O. If ''No'', Synchronet relays the program's stdin/stdout to the user instead. On Windows this setting has no effect. |

===== See Also =====
  * [[config:file_areas|File Areas]]
  * [[config:file_transfers|File Transfers]]
  * [[util:sexyz|SEXYZ]]
  * [[config:cmdline|Command Line Specifiers]]
  * [[:config:|config index]]

{{tag>files}}
