|Configure the Server in the GUI|
Filters allow you to refine the list of files (or directories) designated for transfer. With filters, you indicate which files in the transfer list to skip or include. At runtime, ascp looks for filters in two locations: on the ascp command line, and in aspera.conf. When filtering rules are found in aspera.conf, they are applied before rules on the command line. Filters can be set in the aspera.conf file either from the GUI, or by modifying it directly with an editor or asconfigurator. If no filtering rules are specified, ascp transfers all source files in the transfer list. This topic describes how to configure filters from the GUI.
To specify filtering rules from the GUI, click the Configuration button to open the Server Configuration dialog. Select the File Handling tab, and scroll down to File Filter Pattern List. Click the override checkbox to enable you to enter values to override any inherited settings for this option.
To specify filtering rules, click the button. This opens a Define dialog where you can type in filtering rules. If rules were added earlier, either through the GUI or through aspera.conf, they will appear in the window.
Click the button to add a new filtering rule, or click the button to delete a rule that you've selected.
A rule consists of a "+" or "-" sign (indicating whether to include or exclude), followed by a space character, followed by a pattern. A pattern can be a file or directory name, or a set of names expressed with UNIX glob patterns (described below).
Filtering operates only on the set of files and directories in the transfer list. That is, an include option cannot add files or directories that are not already part of the transfer list.
Filtering is a process of exclusion, and "+" rules act as overrides to any "-" rules that follow them. For example, consider the following example rules when the transfer set is file*:
+ file2 - file[0-9]
- /above/ + /above/belowThe file /above/below is never considered because its parent directory /above/ has already been excluded.
In order to filter directories and files to be transferred, their names are matched against patterns (globs) that include wildcards and special characters. The patterns use the standard globbing syntax found in UNIX systems along with several extensions.
Character case: Case always matters, even if the scanned file system does not enforce such a distinction. For example, "debug" does not match "Debug". To match both, the pattern should be "[Dd]ebug".
Partial matches: With globs, unlike standard regular expressions, the entire filename or directory name must match the pattern. That is, abcdef matches the pattern abc*f but abcdefg does not.
Standard Globbing: Wildcards and Special Characters
|/||The only recognized path separator.|
|\||Quotes any character literally, including itself. The \ character is exclusively a quoting operator, not a path separator.|
|*||Matches zero or more characters, except a / , or the . when preceded immediately by a / character.|
|?||Matches any single character, except a / , or a . when preceded immediately by a / character.|
|[ … ]||Matches exactly one of a set of characters, except a / or a . preceded immediately by a / character.|
|[^… ]||When ^ is the first character, matches exactly one character not in the set.|
|[!… ]||When ! is the first character, matches exactly one character not in the set.|
|[x-x]||Matches exactly one of a range of characters.|
|[:xxxxx:]||For details about this type of wildcard, see any POSIX-standard guide to globbing.|
Globbing Extensions: Wildcards and Special Characters
|/**||Like * but also matches the / character, or a . preceded immediately by a / (that is, the . in /. ).|
|* or /** at end of pattern||Matches both directories and files.|
|/ at end of pattern||Matches directories only. With -N, no files under matched directories or their subdirectories are included in the transfer. All subdirectories are still included, although their files will not be included. However, with -E, excluding a directory also excludes all files and subdirectories under it.|
|no / or * at end of pattern||Matches files only.|
|/ at start of pattern||Must match the entire string from the root of the transfer set. (Note: The leading / does not refer to the system root or the docroot.)|
Standard Globbing Examples
|Wildcard||Example||Matches||Does Not Match|
|\||abc\?||abc?||abc\? abc/D abcD|
|*||abc*f||abcdef abc.f||abc/f abcefg|
|?||abc??||abcde abc.z||abcdef abc/d abc/.|
|[ … ]||[abc]def||adef cdef||abcdef ade|
|[^… ]||[^abc]def||zdef .def 2def||bdef /def /.def|
|[!… ]||[!abc]def||zdef .def 2def||cdef /def /.def|
|[:xxxxx:]||[[:lower:]]def||cdef ydef||Adef 2def .def|
Globbing Extension Examples
|Wildcard||Example||Matches||Does Not Match|
|/**||a/**/f||a/f a/.z/f a/d/e/f||a/d/f/ za/d/f|
|* at end of rule||abc*||abc/ abcfile|
|/** at end of rule||abc/**||abc/.file abc/d/e/||abc/|
|/ at end of rule||abc/*/||abc/dir||abc/file|
|no / at end of rule||abc||abc (file)||abc/|
|/ at start of rule||/abc/def||/abc/def||xyz/abc/def|
|+ rule||Includes all files and directories whose names match rule. Because there is no "-", all the originally specified files and directories are included anyway; in other words, by itself, a "+" rule does nothing.|
|- rule||Excludes all files and directories whose names match rule.|
|Includes all files and directories whose names match rule1. Excludes all that match rule2, except those that also matched rule1.|
|Excludes all files and directories whose names match rule1. Because there is no "-" following the "+", all files and directories not already excluded by the preceding "-" are included anyway; in other words, a trailing "+" rule does nothing to change the result.|
If you plan to use filtering rules, it's best to test them first. An easy way to try filtering rules, or to learn how they work, is to set up source and destination directories and use demo.asperasoft.com as the Aspera server:
The example rules below are based on downloading a directory AAA from demo.asperasoft.com to C:\tmp\dest on your computer:
The examples below use the following file set:
AAA/abc/def AAA/abc/.def AAA/abc/.wxy/def AAA/abc/wxy/def AAA/abc/wxy/.def AAA/abc/wxy/tuv/def AAA/abc/xyz/def/wxy AAA/wxyfile AAA/wxy/xyx/ AAA/wxy/xyxfile
< xxx/yyy = Excluded
xxx/yyy = Included
zzz/ = directory name
zzz = filename
(1) Transfer everything except files and directories starting with ".":
+ * - AAA/**
AAA/abc/def AAA/abc/wxy/def AAA/abc/wxy/tuv/def AAA/abc/xyz/def/wxy AAA/wxyfile AAA/wxy/xyx/ AAA/wxy/xyxfile < AAA/abc/.def < AAA/abc/.wxy/def < AAA/abc/wxy/.def
(2) Exclude directories and files whose names start with wxy
AAA/abc/def AAA/abc/.def AAA/abc/.wxy/def AAA/abc/xyz/def/ < AAA/abc/wxy/def < AAA/abc/wxy/.def < AAA/abc/wxy/tuv/def < AAA/abc/xyz/def/wxy < AAA/wxyfile < AAA/wxy/xyx/ < AAA/wxy/xyxfile
(3) Include directories and files that start with "wxy" if they fall directly under AAA:
+ wxy* - AAA/**
AAA/wxy/ AAA/wxyfile < AAA/abc/def < AAA/abc/.def < AAA/abc/.wxy/def < AAA/abc/wxy/def < AAA/abc/wxy/.def < AAA/abc/wxy/tuv/def < AAA/abc/xyz/def/wxy < AAA/wxy/xyx/ < AAA/wxy/xyxfile
(4) Include directories and files at any level that start with wxy, but do not include dot-files, dot-directories, or any files under the wxy directories (unless they start with wxy). However, subdirectories under wxy will be included:
+ */wxy* - AAA/**
AAA/abc/wxy/tuv/ AAA/abc/xyz/def/wxy AAA/wxyfile AAA/wxy/xyx/ < AAA/abc/def < AAA/abc/.def < AAA/abc/.wxy/def < AAA/abc/wxy/def * < AAA/abc/wxy/.def < AAA/abc/wxy/tuv/def < AAA/wxy/xyxfile
* Even though wxy is included, def is excluded because it's a file.
(5) Include wxy directories and files at any level, even those starting with ".":
+ */wxy* - */wxy/** - AAA/**
AAA/abc/wxy/def AAA/abc/wxy/.def AAA/abc/wxy/tuv/def AAA/abc/xyz/def/wxy AAA/wxyfile AAA/wxy/xyx/ AAA/wxy/xyxfile < AAA/abc/def < AAA/abc/.def < AAA/abc/.wxy/def
(6) Exclude directories and files starting with wxy, but only those found at a specific location in the tree:
AAA/abc/def AAA/abc/.def AAA/abc/.wxy/def AAA/abc/xyz/def/wxy AAA/wxyfile AAA/wxy/xyx/ AAA/wxy/xyxfile < AAA/abc/wxy/def < AAA/abc/wxy/.def < AAA/abc/wxy/tuv/def
(7) Include the wxy directory at a specific location, and include all its subdirectories and files, including those starting with ".":
+ AAA/abc/wxy/** - AAA/**
AAA/abc/wxy/def AAA/abc/wxy/.def AAA/abc/wxy/tuv/def < AAA/abc/def < AAA/abc/.def < AAA/abc/.wxy/def < AAA/abc/xyz/def/wxy < AAA/wxyfile < AAA/wxy/xyx/ < AAA/wxy/xyxfile