This chapter describes management of the TCPware FTP client and server. Topics include:
· Client considerations
· Server security considerations
· Including messages on client login
· ANONYMOUS support
· Server logicals
· Server FTP protocol implementation
Client considerations include creating a startup command file and determining the status on an exit condition.
You can create a system-wide startup file that is executed each time the local client starts an FTP session. To create a startup command file, you need to:
1. Create a file containing the FTP commands you want performed at the beginning of each FTP session. For example:
$ CREATE SYS$COMMON:[SYSMGR]FTP_STARTUP.COM
OPEN IRIS SMITH "Sandy"
SHOW STATUS
Return
$ SET PROTECTION=WORLD:RE SYS$COMMON:[SYSMGR]FTP_STARTUP.COM
The SET PROTECTION command ensures that the client user can read and execute the FTP_STARTUP.COM file.
2. Define the FTP_STARTUP logical to point to the FTP_STARTUP.COM file. For example:
$ DEFINE/SYSTEM/EXEC FTP_STARTUP SYS$MANAGER:FTP_STARTUP.COM
Client users can override this startup file by creating their own. Including the command DEFINE/PROCESS FTP_STARTUP in a user's LOGIN.COM file overrides any DEFINE/SYSTEM/EXEC command in the SYS$MANAGER:SYSTARTUP_V5.COM file.
3. The FTP configuration consists of these questions:
Configuring
FTP-OpenVMS:
Do you want to enable the FTP server? Y
Do you want to enable FTP accounting? Y
Name of host that will run accounting collection program: bigboote.example.com
Port number that accounting collection program listens on: 2222
The last two questions are optional depending on the value of the second question.
See the User's Guide, Chapter 3, FTP: Transferring Files, Startup
Command File about setting up a client-specific FTP_STARTUP.COM
file.
SET DEBUG /CLASS=REPLIES (VERBOSE mode) is enabled by default in TCPware's FTP client so that you do not need to explicitly add the command to the file. However, any VERBOSE command may toggle it to OFF.
See the User's Guide, Chapter 3, FTP: Transferring Files, about setting VERBOSE mode. See your OpenVMS documentation about the SET PROTECTION command.
To exit FTP, use the EXIT command or type Ctrl+Z.
FTP exits with the last error status, if any. DCL command procedures can use the $STATUS and $SEVERITY symbols to test for success or failure of the FTP commands issued. A success status indicates that all commands succeeded. A warning, error, or severe status indicates that one or more commands failed to execute.
When possible, the status code is a System Service (defined in $SSDEF), RMS (defined in $RMSDEF), or shared (defined in $SHRDEF) status. In some cases, status codes are TCPWARE_ private codes with a facility number of 1577.
The FTP server provides security through access restrictions on which IP addresses can connect, login procedures, the use of log files, and the automatic termination of idle control connections.
Access control lists for FTP can be defined in TCPWARE:FTP.CONF. The below table lists the commands that can be in this file.
|
Command |
Description |
|
ALLOW ip-address [mask] |
Connections that match the specified IP address and optional mask are accepted. The default is to allow connections from all IP addresses. |
|
DENY ip-address [mask] |
Connections that match the specified IP address and optional mask are rejected. The default is to deny connections from no IP addresses. |
|
MAX_SERVERS |
The maximum number of servers. This command overrides the existing logical if it is used. |
|
REJECT_BY_DEFAULT |
Connections that do not match an IP address mentioned in an ALLOW statement are rejected. |
|
REJECT_MESSAGE |
The message to be displayed before rejecting the connection. The default is "You are not allowed to access this server." |
|
REQUIRE_TLS YES |
Specifies that user authentications other than anonymous and users that have no password must use TLS authentication. |
|
RFC4217_CERTIFICATE |
Specifies the certificate file to be used with RFC 4217 negotiation. The certificate and key files must be created by an external means such as the SSL certificate tool and be in PEM format. Both a certificate and key file must be specified set up to allow TLS negotiation. On OpenVMS V8.3 and higher you can use @SSL$COM:SSL$CERT_TOOL. |
|
RFC4217_KEY |
Specifies the private key file to be used with RFC 4217 negotiation. The certificate and key files must be created by an external means such as the SSL certificate tool and be in PEM format. Both a certificate and key file must be specified set up to allow TLS negotiation. |
|
STATISTICS ON |
Enable SNMP usage statistics in processSoftware.2.21.1 to .17. This requires that the SNMP Agent be running on the system and that Agent X support is enabled. |
Lines in the file that start with ! (exclamation point) or # (sharp) are considered comments.
· Keep the file short, as each line in the file causes additional startup time for the server.
· If the REJECT_BY_DEFAULT keyword is used in FTP.CONF, comment out any DENY lines that are redundant.
· If using the mask option, comment out any duplicate ALLOW or DENY lines. For example, if you have the line “ALLOW 26.26.26.100 255.255.255.128”, then you do not need the line “ALLOW 26.26.26.x” (where x is 0 to 127), as the mask already covers that host.
· Only printable characters are allowed in the REJECT_MESSAGE message, and the message size must be less than 255 bytes.
Following is an example of an FTP.CONF file:
REJECT_BY_DEFAULT
! but allow
allow 127.0.0.1
allow 123.123.95.1 255.255.255.128
allow 123.123.140.101 255.255.255.192 # blabla
allow 123.123.142.44
allow 123.123.142.42 # Test1
allow 123.123.142.50
allow 123.123.142.51
allow 123.123.142.52
!still deny
deny 123.123.95.2
REJECT_MESSAGE "Access denied. Ask the network administrator for
permission."
Follow these steps to configure the TCPware FTP server to allow TLS authentication:
1. Generate or obtain certificate and key files. On OpenVMS V8.3+ SSL$COM:SSL$CERT_TOOL can be used to do this.
2. Place the certificate and key file where you want them and verify that the protection is set such that world has no access.
3. Edit TCPWARE:FTP.CONF and add the RFC4217_CERTIFICATE and RFC4217_KEY commands to specify the location of the certificate and key files.
4. Optionally add REQUIRE_TLS command to TCPWARE:FTP.CONF
5. Restart the FTP server with @TCPWARE:RESTART FTP
The FTP server uses the same login procedures as DECnet network connections and does not support OpenVMS accounts with two passwords.
The TCPware FTP server keeps a log of all FTP transactions that occur after login between the client and the server in an FTPSERVER_DTP.LOG file in the user's login directory on the server system. A log file is created for each FTP client session. A new log is written when a new session starts, and you can specify a number of log files to retain. The default is to retain only the latest. Users can change this value by defining it in their LOGIN.COM file, or it can be defined on a system-wide basis if this is desired for all users.
|
Note: If the TCPware FTP server process does not start or mysteriously disappears, examine the beginning of FTPSERVER_DTP.LOG for error messages. Because the system-wide login command procedure (SYS$MANAGER:SYLOGIN.COM) and the user's LOGIN.COM are executed as part of the server process creation, errors in these procedures can cause the server process to terminate. In most instances, however, the reason for the process terminating appears at the beginning of the FTPSERVER_DTP.LOG file.
|
TCPWARE:FTPSERVER_DTP.COM runs when an FTP user logs in. It does the following things:
1. Purges the old versions of SYS$LOGIN:FTPSERVER_DTP.LOG, keeping TCPWARE_FTP_SERVER_LOG_LIMIT versions of the file.
2. If the logical TCPWARE_FTP_SET_DEFAULT_TO_ROOT is defined, it sets the default to TCPWARE_FTP_username_ROOT (or TCPWARE_FTP_ROOT). If TCPWARE_FTP_SET_DEFAULT_TO_ROOT is not defined, the user is not changed. This is traditional TCPware behavior.
3. Defines logicals about the remote connection:
· defines TCPWARE_FTP_GET_REMOTE_INFO, then runs TCPWARE:FTP_SERVER (it exits immediately afterwards)
· TCPWARE_FTP_ADDRESS = remote host IP address
· TCPWARE_FTP_HOSTNAME = remote host name
· TCPWARE_FTP_LOCAL_ADDRESS = local host IP address
· TCPWARE_FTP_ANONYMOUS_PASSWORD (if logging in as ANONYMOUS, this is the string the anonymous user supplied for the password).
· Deassigns TCPWARE_FTP_GET_REMOTE_INFO.
|
Note: The values of these logicals can be used to control later aspects of the FTP session by adding DCL commands after this point.
|
4. Sets the default values for the following logicals if they are not defined: TCPWARE_FTP_SEMANTICS_VARIABLE_IGNORE_CC TRUE TCPWARE_FTP_UNIX_STYLE_CASE_INSENSITIVE TRUE TCPWARE_FTP_DISALLOW_UNIX_STYLE TRUE
5. Starts the FTP service program TCPWARE:FTP_SERVER.
The following sample log file contains the FTP transactions involved when the user logs in under the username HOLMES, issues a DIRECTORY command, and then retrieves the file FOO.BAR.
-------------------------------------------------------
FTP Login request received at Mon Jun 14 19:05:10 2020
from remote IP address 127.0.0.1
-------------------------------------------------------
>>> 230 User HOLMES logged into U1:[HOLMES] at Mon 07-Jun-2020 19:05,
job 3a.
<<< TYPE A
>>> 200 Type A ok.
<<< STRU F
>>> 200 Stru F ok.
<<< MODE S
>>> 200 Mode S ok.
<<< PORT 127,0,0,1,4,14
>>> 200 Port 4.14 at Host 127.0.0.1 accepted.
<<< LIST
>>> 150 List started.
>>> 226 Transfer completed.
<<< PORT 127,0,0,1,4,15
>>> 200 Port 4.15 at Host 127.0.0.1 accepted.
<<< RETR foo.bar
>>> 150 ASCII retrieve of USERS:[HOLMES]FOO.BAR;1 started.
>>> 226 Transfer completed. 210 (8) bytes transferred.
<<< QUIT
>>> 221 QUIT command received. Goodbye.
HOLMES job terminated at 11-JUN-2020 19:05:23.08
By setting the logical name TCPWARE_FTP_SERVER_LOG_LIMIT in the LOGIN.COM file, you can specify that log files be retained. Set the logical name to a dash (-) to retain all log files or specify a number in the range of 1 to 32000.
|
Note: If you are not going to add the TCPWARE_FTP_SERVER_LOG_LIMIT logical to your login.com file but you want to make this a system-wide logical, use the following syntax: define/system/exec tcpware_ftp_server_log_limit 42.
|
Directory size restrictions limit the number of potential files that can be created. If you do not specify a number or value, one log file is created or overwritten for each FTP session. Use the DCL PURGE command to delete unneeded log files. The following example specifies that 42 log files be retained:
$ DEFINE TCPWARE_FTP_SERVER_LOG_LIMIT 42
When TLS authentication is used the FTP server will create an additional log file in TCPWARE_SPECIFIC:[TCPWARE.FTPS]FTPS.LOG. These files contain status information from the process that controls the encrypted command channel.
The FTP server lets you define three logicals for access restrictions to specific directory trees. These include the TCPWARE_FTP_ROOT logical for system-wide access restrictions, the TCPWARE_FTP_ANONYMOUS_ROOT logical for ANONYMOUS user access restrictions, and the TCPWARE_FTP_username_ROOT logical for specific username access restrictions. See Server Logicals and ANONYMOUS Support.
The FTP server creates a log file in your default directory each time a client user successfully logs in. This FTPSERVER_DTP.LOG file contains information about files transferred during the FTP session. If client users have problems logging in and are sure they specified a proper username and password, you can check the SYLOGIN and user account login command procedures for commands that could have caused the login to fail.
Examining the FTPSERVER_DTP.LOG file might help isolate the problem. You may need to execute some operations only if the process mode is interactive. (Use the F$MODE() lexical function to determine the mode and then skip around the offending commands if not an interactive login.) The FTP server runs in network mode.
If you suspect break-in attempts, you can also define the TCPWARE_FTP_LOGFILE system logical to specify the name of a log file.
If the control connection (other than during a data transfer) is idle for more than 10 minutes, the FTP server aborts the connection, unless you change the idle timeout value using the TCPWARE_FTP_IDLE_TIMEOUT logical.
Partial support for RFC 2789 (Network Services Monitoring MIB) has been added to FTP. This feature is enabled with the STATISTICS ON command in the TCPWARE:FTP.CONF file. Information is maintained only while the service is active. The following items from the Network Services Monitoring MIB (RFC 2789) are available in the enterprises.105.2.21 MIB:
|
ApplAccumulatedInboundAssociations |
(Counter) the total number of connections that the FTP Listener program has serviced since it was started. enterprises.105.2.21.10 |
|
ApplDescription |
(String) Description of the program/application. This is the banner that gets printed when the client connects to the FTP Listener program. enterprises.105.2.21.16 |
|
ApplInboundAssociations |
(Counter) The number of connections currently active. enterprises.105.2.21.8 |
|
ApplIndex |
(Integer) unique application index. The port FTP is offered on (21). enterprises.105.2.21.1 |
|
ApplLastChange |
(TimeTicks) the value of sysUpTime when the FTP Listener program entered the current state. enterprises.105.2.21.7 |
|
ApplLastInboundActivity |
(TimeTicks) the value of sysUpTime at the time the most recent connection was established. enterprises.105.2.21.12 |
|
ApplName |
(String) FTP. enterprises.105.2.21.2 |
|
ApplOperStatus |
(Integer) the operational status of the FTP Listener program; the values are: up(1), down(2), halted(3), congested(4), restarting(5), quiescing(6). Some of these values may not be used. enterprises.105.2.21.6 |
|
ApplRejectedInboundAssociations |
(Counter) the number of connections that have been rejected (due to not being allowed from the access list values). enterprises.105.2.21.14 |
|
ApplUptime |
(TimeTicks) the value of the SNMP variable sysUpTime when the FTP Listener program was started. enterprises.105.2.21.5 |
|
ApplVersion |
(String) the version of the FTP Listener program. enterprises.105.2.21.4 |
This feature requires the SNMP Agent X functionality. To use this SNMP must be configured to have Agent X service enabled, and to allow the system's IP and the local host addresses (127.0.0.1) to each be an AGENTX_PEER. See Chapter 7 for more information on SNMP and Agent X. This information can be displayed with the NETCU SHOW SNMP MIB_VARIABLE command.
TCPware can record accounting information from services that have been enabled. Currently this includes FTP and SMTP. The accounting information includes information about when a network session took place and how much data was transferred. The accounting facility is enabled from @TCPWARE:CNFNET ACCOUNTING and reads TCPWARE:ACCOUNTING.CONF for additional configuration information. The format of the accounting records is described in TCPWARE_ROOT:[TCPWARE.EXAMPLES]ACCOUNTING.H
A sample program using this is in TCPWARE_ROOT:[TCPWARE.EXAMPLES]ACC_DUMP.C
You must configure FTP and session accounting to activate the accounting function.
To configure FTP, do the following:
$ @TCPWARE:CNFNET FTP
The following information displays on your screen:
TCPware(R) for OpenVMS Version 6.1 Network Configuration procedure for:
TCP/IP Services:
FTP-OpenVMS
NFS-OpenVMS Client
NFS-OpenVMS Server
SMTP-OpenVMS
TELNET-OpenVMS
Kerberos Services
SSH-OpenVMS Server
This procedure helps you define the parameters needed to get
TCPware(R) for OpenVMS running on this system.
This procedure creates the configuration data file,
TCPWARE_SPECIFIC:[TCPWARE]TCPWARE_CONFIGURE.COM, to reflect your
system's configuration.
Type <return> to continue...
Configuring FTP-OpenVMS:
Do you want to enable the FTP server [YES]: Return
Do you want to enable FTP accounting [NO]: YES
Name of host that will run accounting collection program [construction.example.com]:
RETURN
Port number that accounting collection program listens on []: 2222
Do you want to restart FTP-OpenVMS [NO]: YES
Shutting down FTP-OpenVMS ...
Starting FTP-OpenVMS ...
%RUN-S-PROC_ID, identification of created process is 00000195
$
To configure Session Accounting, follow these steps:
1. Edit the ACCOUNTING configuration file.
2. Invoke CNFNET to enable and start ACCOUNTING:
$ @TCPWARE:CNFNET ACCOUNTING
The Accounting configuration file is TCPWARE:ACCOUNTING.CONF. The Accounting configuration file defines:
· The port the Accounting program listens on. This should be an unused port, not the port for the service on which logging is being enabled, and the same port specified to FTP or SMTP.
· The name of the file used for accounting records. This file is opened shareable and new records are always appended to it. To start a new file, stop the Accounting program, delete (or rename) the existing file, and restart the Accounting program.
· The IP addresses of systems that are allowed to write accounting records to this host.
After editing the configuration, stop and restart the Accounting program so that the changes can take effect.
Follow these guidelines when entering data in the Accounting configuration file:
· Allow one line for each item.
· Enter information in any order; in upper- or lowercase.
· Use a pound sign (#) or exclamation point (!) to denote comments. The Accounting facility ignores all information following these characters.
The commands that can be in TCPWARE:ACCOUNTING.CONF are:
|
PORT port_number |
The TCP port that the accounting program should listen on. |
|
PEER ip-address |
The IP address of a host that is allowed to log records with the accounting software. |
|
FILENAME filename |
The name of the file that the accounting records will be written to. The TCPWARE: device is assumed if a device is not specified as part of the file specification. |
$ @TCPWARE:CNFNET ACCOUNTING
TCPware accounting consists of two components: The accounting record logger, which this procedure configures and controls, and the services that can use the accounting process.
This procedure controls the startup of the accounting record logger. The details such as the name of the accounting file, the port that the accounting record logger listens on, and the list of IP addresses that can use the accounting logger are controlled by TCPWARE:ACCOUNTING.CONF:
Do you want to activate the Accounting listener on this host [NO]: Y
To view accounting information, do the following:
$ TCPWARE ACCOUNTING/INPUT=accounting_data_file
[/output=output_file] -
_$[/since=start_date] [/before=end_date] [/protocol={SMTP, FTP,
MAIL}] [/CSV]
· accounting_data_file is the name of the logging file you want to see.
· output_filename is the name of the file you want to call this information. If this field is omitted, the information displays to the terminal screen.
·
start_date is the beginning
date you want the command to start with. The date format is
[DD-MMM-YYYY [:]] [hh:mm:ss]cc] If not specified, all records display up to the
end of the data found.
o DD is the day of the month, counting from 01.
o MMM is the abbreviation for the month, like JAN, FEB, MAR.
o YYYY is the number of the year, including the century (e.g. 1999, 2021).
o hh is the hour, from 00 to 23.
o mm is the minute, from 00 to 59.
o ss is the second, from 00 to 59.
o cc is hundredths of seconds.
The time is always in local time.
· end_date is the ending date you want the command to end with. The date format is the same as for start_date. If not specified, all records display until the end of the file.
· protocol is any combination of SMTP, FTP, or MAIL.
· CSV is the Comma Separated Values, for input to products like Excel.
The accounting file is written using OpenVMS RMS records. The format of these records is defined in TCPWARE_ROOT:[TCPWARE.EXAMPLES]ACCOUNTING.H, and listed below:
/*
* PDU format
*/
struct accountingPDU {
char version;
char type; /* type of record */
/*
* FTP:
* C - Client
* S - Server
*
* SMTP:
* N - Network delivery (send)
* L - Local delivery (received)
* F - Forwarded
* R - Returned
* D - Delivery Receipt
* Q - ReQueued
*
*/
char flags; /* not currently used */
char reserved; /* for future use */
int payload_length; /* length (in bytes) of data after header */
int port; /* IP port of reporting service - 25 SMTP, 21 - FTP */
int reporterIP; /* IP address of reporter */
};
struct FTPaccounting_data {
struct accountingPDU header;
int start_time[2]; /* VMS time that session started */
int end_time[2]; /* VMS time that session ended */
int datasent; /* KBytes of file data sent */
int datarecv; /* KBytes of file data received */
int filessent; /* Number of files sent */
int filesrecv; /* Number of files received */
int partnerIP; /* IP address of partner */
char user[12]; /* username that operations were done under */
};
struct SMTPaccounting_data {
struct accountingPDU header;
int date[2]; /* Time of activity */
int msg_size; /* size of message in bytes */
int from_str_size; /* size of From: string */
int to_str_size; /* size of To: string */
char from_to_str[1]; /* text of From & To string */
};
#define accounting_Close 1
typedef struct accounting_peer_info {
struct accounting_peer_info *next;
ulong ia;
} accounting_peer_info;
#define MAX_STRING_LEN 255
You can include special informational text messages in a specified file in directories so that the message appears when an FTP client user logs in or changes to that directory. The TCPWARE_FTP_MESSAGE_FILE logical determines the filename to check in each directory. This feature is particularly helpful for ANONYMOUS FTP client users to get informational messages when changing directories (see the next section for a description of ANONYMOUS support).
For example, the FTP_CONTROL.COM file that you activate on startup includes the following line commented-out:
$! DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_MESSAGE_FILE ".MESSAGE"
You can activate this logical with the default .MESSAGE file definition, or change it to WELCOME.TXT, for example. What the file should contain depends on the context. If the file is in a login directory, it should contain a general message about the system, such as Welcome to OpenVMS AXP v8.2 (IRIS). If the file is in another directory to which the user can move, it should have specifics about the directory, such as Welcome to the SUPPORT directory. It contains TECHNICAL SUPPORT information.
The FTP client user must set VERBOSE mode to be able to see the messages. VERBOSE (REPLIES) mode is set by default in TCPware's FTP client.
The FTP command line client interprets the exclamation point (!) as the start of a comment. To send an exclamation point to the server it must be enclosed in quotes ("). The quote character (") must be doubled up in the string if it is to be sent to the server. For example:
FTP>“! send this string to the server.”
sends the whole line, including the exclamation point and the period.
The FTP command line client prompts with the name of the opened node when the TCPWARE_FTP_PROMPT_NODENAME logical is defined.
The FTP server provides special support for ANONYMOUS accounts.
To set up an ANONYMOUS account, issue commands using the OpenVMS AUTHORIZE utility:
$ AUTHORIZE
UAF>ADD ANONYMOUS/PASSWORD=GUEST/UIC=[uic] -
_UAF>[/other
qualifiers] /NOPWDEXP/NOPWDLIFE
UAF>MODIFY
ANONYMOUS/NOLOCAL/NOBATCH/NOREMOTE/NODIALUP
UAF>MODIFY ANONYMOUS/PRIV=NONETMBX/DEFPRIV=NONETMBX
The /NOPWDEXP and /PWDLIFE=NONE qualifiers ensure that the password remains active indefinitely. The /NOLOCAL, /NOBATCH, /NOREMOTE, and /NODIALUP qualifiers prevent access to the account from those sources. Removing the NETMBX privilege prevents DECnet access.
See your OpenVMS documentation for details on the AUTHORIZE utility.
The FTP server can recognize other names as anonymous names as well if the logical TCPWARE_ANONYMOUS_USERNAMES is defined. If the name “ANONYMOUS” is still desired, then it should be included in the definition:
$ DEFINE TCPWARE_ANONYMOUS_USERNAMES “ANONYMOUS,GUEST”
FTP users have automatic read access through ANONYMOUS accounts. You can also assign write, rename, or delete access by defining the TCPWARE_FTP_ANONYMOUS_RIGHTS logical.
Be aware of the following:
· You must create the ANONYMOUS account to use the password GUEST. If the account has any other password, users cannot log in. If the account has another password, use the MODIFY ANONYMOUS /PASSWORD=GUEST/NOPWDEXP command in the AUTHORIZE utility to change it.
· It is recommended that the ANONYMOUS account use the rooted logical (such as ANONYMOUS_ROOT) to point to the top level directory and set the default to ANONYMOUS_ROOT:[000000]. In this way, when a client changes the directory to a slash (/) (or uses a slash in front of a directory specification, as is the case with some web browsers), SYS$DISK:[000000] maps to this root directory. (Note that this mapping is independent of the access restrictions applied by the TCPWARE_FTP_*_ROOT logicals.)
· If you define the TCPWARE_FTP_ANONYMOUS_ROOT logical (or the TCPWARE_FTP_ROOT logical on a system-wide level), the system restricts ANONYMOUS user access to files in the root directory and subdirectories only. When the ANONYMOUS user logs in, the root directory becomes the default.
· In response to a username, the system sends a reply message of 331 Send ident as Password instead of the usual 331 Password required.
· If you define the TCPWARE_FTP_ANONYMOUS_230_REPLY logical, the system uses it to generate the reply message when the ANONYMOUS user logs in. If you do not define this logical, the system uses the default 230 reply instead.
· Using a hyphen (-) as the first character of the password causes the system to turn off the message generated by the logicals. The system sends the default 230 reply instead.
· If you define the TCPWARE_FTP_LOGFILE logical, the server writes a record to the log file:
date/time ANONYMOUS FTP login successful (password) from ia, port
|
Note: You must restart FTP after setting this logical by issuing this command: $ @tcpware:restart ftp
|
Each command is logged with the following format:
date/time ANONYMOUS FTP user (password) at ia, job 120 reply to user command job 120 PWD
The response to each command is logged with the following format:
date/time ANONYMOUS FTP user (password) from (internet address), job (pid), (reply string)
or
date/time user name from (internet address), job (pid), (reply string)
· SITE SPAWN is not a valid command with ANONYMOUS FTP.
The FTP server supports the following special system-definable logicals.
|
Note: With the root logicals (TCPWARE_FTP_ROOT, TCPWARE_FTP_ANONYMOUS_ROOT, and TCPWARE_FTP_username_ROOT), any logical you refer to in the equivalence name (such as a disk name) must also be an executive mode, system table logical. With all of these logicals, if the user account cannot access the directory, FTP operations will fail with the error %RMS-E-PRV.
|
The TCPWARE_FTP_220_REPLY logical defines a message displayed when a user connects to the server and can log in. This message replaces the default message.
You can define lines of the message text, one comma-separated equivalence string for each line. You can also specify a file that contains the message text by defining an equivalence string starting with the at-sign (@) and followed by the complete file specification. For example, you can define the welcome text equivalence string as follows:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_220_REPLY -
_$ "**AUTHORIZED USE ONLY **",-
_$ "bart.example.com (192.168.34.56)", -
_$ "TCPware FTP (c) Process Software"
Alternately, you can include the last three equivalence strings in an FTP_WELCOME.TXT file and define the logical as follows:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_220_REPLY -
_$ "@SYS$MANAGER:FTP_WELCOME.TXT"
In either case, when a user connects to a host, the message appears as follows:
220-** AUTHORIZED USE ONLY **
220-bart.example.com (192.168.34.56)
220 TCPware FTPD (c) Process Software
_Username []:
The TCPWARE_FTP_221_REPLY logical defines a message to appear when a user ends the FTP session. If you do not define this logical, TCPware uses the default message instead. As with TCPWARE_FTP_220_REPLY, you can define a text string or file. For example:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_221_REPLY -
_$ "Connection to FTP server has been
closed"
Now, when the user closes the FTP connection, the following message appears:
221 Connection to FTP server has been closed
The TCPWARE_FTP_230_REPLY logical defines a message to appear when a user successfully logs in. If you do not define this logical, TCPware uses the default message instead. As with TCPWARE_FTP_221_REPLY, you can define a text string or file. For example:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_230_REPLY -
_$ "Login successful"
Now, when the user logs in using FTP, the following message appears:
230 Login successful
The TCPWARE_FTP_421_REPLY logical defines a message sent when a user connects to the server but should not log in. After sending the message, the connection closes. For example, you can define this logical to prevent FTP access for a short time. Be sure to deassign the logical after this period to allow FTP access again. As with TCPWARE_FTP_230_REPLY, you can define a text string or file. For example:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_421_REPLY -
_$ "System maintenance in progress until
17:30"
Now, when the user connects to the host through FTP, the following message appears and then the connection closes:
421 System maintenance in progress until 17:30
|
Note: The TCPWARE_FTP_421_REPLY logical has precedence over the TCPWARE_FTP_220_REPLY logical.
|
If the SYSTEM logical TCPWARE_FTP_ACCESS or TCPWARE_FTP_username_ACCESS (to specify a particular username) is defined to any combination of NOLIST, NOWRITE, NOREAD, NOSPAWN, or NODELETE, then the FTP server will not allow the specified actions.
The logical name TCPWARE_FTP_ALL_VERSIONS requests the NLST and LIST commands to display all versions of the specified files. If TCPWARE_FTP_ALL_VERSIONS is defined as TRUE, the logical name TCPWARE_FTP_STRIP_VERSION has no effect. If this logical is defined as FALSE, NO, or 0 (zero), only the latest version of files in VMS-style directories displays. The default is to display all versions in VMS-style directories.
|
Note: TCPWARE_FTP_ALL_VERSIONS is ignored if the FTP server is in UNIX emulation mode.
|
By default, the FTP server does not allow file transfers for CAPTIVE accounts. However, by defining the TCPWARE_FTP_ALLOWCAPTIVE logical, you can allow CAPTIVE accounts to use all FTP commands except SITE SPAWN. Define the logical as follows:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_ALLOWCAPTIVE " "
You must also modify the CAPTIVE account procedure to allow the FTP server to start the data transfer process. The procedure can check if the logical TT is equal to TCPWARE:FTPSERVER_DTP.COM and exit out of the login procedure, as follows:
$! Check if this is the TCPware FTP
data transfer process:
$ IF F$LOGICAL("TT") .EQS. "TCPWARE:FTPSERVER_DTP.COM" THEN
EXIT
$! Refuse other network connections (such as DECnet):
$ IF F$MODE() .EQS. "NETWORK" THEN LOGOUT
$! (or allow by using "...THEN EXIT" above)
$! Remainder of CAPTIVE procedure follows:
$....
The TCPWARE_FTP_ANONYMOUS_230_REPLY logical defines a message to appear when an ANONYMOUS user successfully logs in. If you do not define this logical, TCPware uses the default message instead. As with TCPWARE_FTP_230_REPLY, you can define a text string or file. For example:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_ANONYMOUS_230_REPLY -
_$ "ANONYMOUS login successful"
Now, when a user logs in using the ANONYMOUS account, the following message appears:
230 ANONYMOUS login successful
The TCPWARE_FTP_ANONYMOUS_RIGHTS logical lets you define write, rename, and delete access rights for the ANONYMOUS FTP user in addition to read access. For example:
$ DEFINE/SYS/NOLOG/EXEC TCPWARE_FTP_ANONYMOUS_RIGHTS –
_$ "WRITE,RENAME,DELETE"
|
WRITE |
Lets you PUT, COPY, SEND, APPEND, and MPUT files into the ANONYMOUS FTP area. It also allows execution of the CREATE/DIRECTORY command. |
|
RENAME |
Lets you rename files in the ANONYMOUS FTP area. |
|
DELETE |
Lets you delete files and directories from the ANONYMOUS FTP area. |
The definition of these rights does not override the actual file protections. If a directory does not allow write access, users cannot write to the directory even though the TCPWARE_FTP_ANONYMOUS_RIGHTS logical grants them write access. Likewise, if a file does not allow delete access, users cannot delete it even if the TCPWARE_FTP_ANONYMOUS_RIGHTS logical grants them delete access.
The TCPWARE_FTP_ANONYMOUS_ROOT (system level, executive mode) logical defines access restrictions for users logged in as ANONYMOUS. For example, you can set access restrictions for users logged in as ANONYMOUS to allow access to just the ANONYMOUS$USER directory and its subdirectories, as follows:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_ANONYMOUS_ROOT ANONYMOUS$USER:
If you do not set this logical, the FTP server defaults to the setting in the TCPWARE_FTP_ROOT logical (described above) if it exists.
This logical limits the information given out on connection or when using the STAT command
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_CONNECT_BANNER “FTP server name”
If this logical is defined as whitespace, operating system and TCP stack information is removed from the FTP server connection banner. If this logical is defined with a specific FTP server name, the information banner does not appear in response to the STAT command.
This logical controls whether UNIX-style filename parsing is done. The default value for TCPWARE_FTP_DISALLOW_UNIX_STYLE is TRUE, UNIX-style filename parsing is not handled. If you want UNIX-style filename parsing, you must define this logical as FALSE. When UNIX-style parsing is enabled, it is not normally done until a CD command has been done with a directory specification that contains a “/” in it. For example:
FTP>cd ../my_directory
|
Note: For some FTP clients (TCPware is one of them) you will have to enclose the directory specification in quotes (“ ”) when it contains a slash (/) to prevent the client from attempting to parse it.
|
To exit UNIX-type filename parsing, use a CD command with either the “[” or “<” character in the directory specification. For example:
FTP>cd [-.my_directory]
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_DISALLOW_UNIX_STYLE FALSE
Some graphical display FTP clients expect the output of directory commands to be in a UNIX system format. To enable this UNIX format, use the following either at the system level or in the user's LOGIN.COM:
$ DEFINE TCPWARE_FTP_DISALLOW_UNIX_STYLE FALSE
and
$ DEFINE TCPWARE_FTP_UNIX_STYLE_BY_DEFAULT ANYTHING
If this logical is defined (any value) then the FTP server will not allow wildcard deletes to be done.
If this logical is defined, the reporting of the estimate of the number of bytes to be transferred in the 150 response line is suppressed. Some FTP clients expect this number to be exact. The FTP server is unable to determine an exact count without processing the entire file, so an estimate of the number of bytes used to store the file is returned. The inaccuracy comes from the differences in the way OpenVMS records and line breaks are handled.
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_DONT_REPORT_FILESIZE TRUE
Defines the default allocation /extension quantity of blocks for new files and appends. See FAB$W_DEQ in the OpenVMS Record Management Services Manual for an explanation of the effect of this.
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_EXTENSION_QUANTITY n
When a new connection arrives at the FTP server it attempts to resolve the name of the host that originated the connection. If this process takes a long time, it can stall all other connections, both active and new. To adjust how long the FTP server is allowed to take to look up the host name, set the logical TCPWARE_FTP_GETHOST_MAX_TIME to the VMS delta time that can elapse before it gives up. The default value is 10 seconds (0 0:0:10).
If you want to change the timeout for FTP connection attempts to something other than the default of 10 minutes, use the TCPWARE_FTP_IDLE_TIMEOUT system logical. The FTP server checks the timeout when you enter and complete a command. Therefore, you can set this logical at any time, and it effectively changes the idle timeout for open, non-idling connections as well as for any future ones. Make sure to use delta time for the time syntax. For example:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_IDLE_TIMEOUT "0 00:20:00"
This example changes the idle timeout to 20 minutes. If omitted, the default is 10 minutes. If you set the value to 0, idle timeout is disabled.
Disabling idle timeout is not recommended as it creates a potential denial of service security problem.
By default, the FTP server ignores Unix-style dash options on LIST and NLST when in Unix mode (for example, the “-l” in “ls -l”). Define this to be FALSE to tell the FTP server to pay attention to Unix-style dash options.
$ DEFINE /SYSTEM /EXEC TCPWARE_FTP_IGNORE_UNIX_DASH_OPTIONS FALSE
The TCPWARE_FTP_LOGFILE (system level, executive mode) logical can be defined to specify the name of a log file. This is good if you suspect break-ins to the FTP server. For example:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_LOGFILE
-
_$ SYS$COMMON:[SYSMGR]FTPLOGIN.LOG
|
Note: You must restart FTP after setting this logical by issuing this command: $ @tcpware:restart ftp
|
If this logical exists, the FTP server writes a record to the specified file each time a user attempts to log in. Each record includes the date and time, the remote host's internet address, and whether the login succeeded.
This logical specifies the name of the file to which ALL commands and responses to ANONYMOUS FTP services are logged. If TCPWARE_FTP_LOG_ALL_USERS is also defined, then commands and responses for all users are logged.
This logical causes all commands and responses to be logged to the file defined by TCPWARE_FTP_LOGFILE. The default (when this logical is not defined) is to just log the commands and responses for anonymous users.
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_LOG_ALL_USERS TRUE
When doing an NLST function (which is used as part of MGET) the FTP server now returns the filenames without making them lower case to preserve the case on ODS-5 disks. To restore the old behavior of making the filenames all lowercase define this logical to TRUE.
The logical TCPWARE_FTP_MAX_PRE_ALLOCATION may be defined to limit the size that a file will be pre-allocated to when the size information is available at transfer time. This can be important when transferring very large files, as it can take a long time to pre-allocate the file at the start of the transfer and timeout routines in FTP and/or firewalls may cause connections to be dropped. This logical does not have any effect for STRU OVMS transfers of indexed, Contiguous, on Contiguous, Best Try files; these files need to have accurate allocation size information at the start of the transfer.
The FTP client and the FTP server normally check the record size of an ASCII transfer and disallow more than 8192 byte records (as a sanity check). However, you can define the TCPWARE_FTP_MAXREC logical to override the default of 8192. The definition of the TCPWARE_FTP_MAXREC logical is commented out but defined in the FTP_CONTROL.COM file as follows:
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_MAXREC 8192
Note that the maximum record size supported by OpenVMS is 65535.
The logical name TCPWARE_FTP_MAX_SERVERS allows the maximum number of servers to be set. The default is 10000.
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_MAX_SERVERS "1500"
The TCPWARE_FTP_MESSAGE_FILE logical defines the message file the FTP user sees when connecting to the server or moving between directories. The definition of the TCPWARE_FTP_MESSAGE_FILE logical is commented out but defined in the FTP_CONTROL.COM file as follows:
$ !DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_MESSAGE_FILE ".MESSAGE"
See Special Messages.
If the logical TCPWARE_FTP_NEW_LOGFILE is defined, then FTP_LISTENER opens a new logfile to record anonymous actions rather than appending to the existing one.
If the TCPWARE_FTP_NOKEEPALIVES logical is defined then the FTP server will not send keepalives on the control channel. The KEEPALIVE command allows the FTP client program to toggle whether it desires keepalives to be sent on the control channel. The SET [NO]KEEPALIVE command allows the FTP client to explicitly set whether it desires keepalives on the control channel.
If the TCPWARE_FTP_NO_PASV_SECURITY logical is defined then the FTP server does not perform the security check of comparing the IP address of the accepted port with the command port while operating in passive mode.
If the TCPWARE_FTP_ONLY_BREAK_ON_CRLF logical is set and an ASCII file is transferred, a new line is created in the file upon receipt of a carriage return/line feed sequence.
If this logical is not set and an ASCII file is transferred, a new line is created upon receipt of either a carriage return/line feed sequence or a line feed.
$ DEFINE TCPWARE_FTP_ONLY_BREAK_ON_CRLF anything
The logical TCPWARE_FTP_PASSWORD_WARNING_MESSAGE defines the message that the FTP server displays when the user's password is going to expire within the warning time. If the amount of time before the password expires is to be displayed, use a %s in the logical.
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_PASSWORD_WARNING_MESSAGE "%s"
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_PASSWORD_WARNING_MESSAGE "message"
The logical TCPWARE_FTP_PASSWORD_WARNING_TIME uses the VMS delta time to specify the minimum remaining lifetime for the user's password. If the remaining lifetime is greater than the VMS delta time, then no message is displayed. It is necessary to define this value to enable checking for the remaining lifetime of a password.
$ DEFINE/SYSTEM/EXEC @TCPWARE_FTP_PASSWORD_WARNING_TIME –
_$ “dddd hh:mm:ss.hh”
The TCPWARE_FTP_RECEIVE_THRESHOLD logical specifies the amount of buffer space that can be used to buffer transmitted data on the data socket. The default value if 6144. If this logical is defined and it begins with a /, then it specifies the fraction of the window size; if only a fraction is specified, then it indicates the number of bytes to be used.
$ DEFINE/SYSTEM/EXECUTIVE TCPWARE_FTP_RECEIVE_THRESHOLD 6144
If this logical is defined, and the FTP server is not operating in UNIX mode, it recodes filenames that are not legal OpenVMS file names in the same manner that it would normally recode filenames when operating in UNIX mode. This is useful for handling filenames with multiple dots (.), spaces, and other characters that VMS does not allow in filenames while retaining the OpenVMS directory syntax.
$ DEFINE TCPWARE_FTP_RECODE_NONVMS_FILE_NAMES anything
The TCPWARE_FTP_ROOT (system level, executive mode) logical defines the system-wide default directory access restrictions for client users. The logical may be defined as a single directory or a search list of directories.
For example, you can restrict all users logged in via FTP to the COMMON$USER directory and its subdirectories, as follows:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_ROOT COMMON$USER:
The FTP server defaults to this logical if the TCPWARE_FTP_ANONYMOUS_ROOT or TCPWARE_FTP_username_ROOT logicals (described in the next section) are not set.
|
Note: The user is not placed automatically in this directory upon successful login unless the logical TCPWARE_FTP_SET_DEFAULT_TO_ROOT is defined to True.
|
The TCPWARE_FTP_username_ROOT (system level, executive mode) logical defines access restrictions for an FTP client logging in as username. The logical may be defined as a single directory or a search list of directories.
For example, you can restrict user CLARK to the COMMON$USER:[CLARK] directory and its subdirectories, as follows:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_CLARK_ROOT COMMON$USER:[CLARK]
Because the FTP server restricts access by default to the directory setting in the TCPWARE_FTP_ROOT logical (described earlier), if it exists, you may want to use the special wildcard (*) setting with the TCPWARE_FTP_username_ROOT logical to bypass the default for username. For example, to restrict the bulk of users to DISK$SYS_LOGIN, restrict users KATE and PAUL to ENG$DISK, but allow SYSTEM full access to locations covered by its account, define the following logicals:
$ DEFINE/SYSTEM/EXEC
TCPWARE_FTP_ROOT DISK$SYS_LOGIN ! default
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_KATE_ROOT ENG$DISK
! limits KATE
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_PAUL_ROOT ENG$DISK
! limits PAUL
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_SYSTEM_ROOT *
! full SYSTEM
ANONYMOUS user access restrictions are described under TCPWARE_FTP_ANONYMOUS_ROOT.
|
Note: The user is not placed automatically in this directory upon successful login unless the logical TCPWARE_FTP_SET_DEFAULT_TO_ROOT is defined to TRUE.
|
If the TCPWARE_FTP_SEMANTICS_FIXED_IGNORE_CC logical is defined to TRUE, then GET operations of fixed lengths record files will not have a carriage return-line feed (CRLF) added to the end of each record.
$ DEFINE TCPWARE_FTP_SEMANTICS_FIXED_IGNORE_CC TRUE
When this logical is defined to TRUE, files with variable length records and carriage return carriage control will NOT have a new line character inserted after each line when the file is transferred in image (binary) mode. The default is TRUE and is defined in FTPSERVER_DTP.COM.
$ DEFINE TCPWARE_FTP_SEMANTICS_VARIABLE_IGNORE_CC FALSE
Users can change this value by defining it in their LOGIN.COM file, or it can be defined on a system-wide basis if this is desired for all users.
This specifies the upper and lower port boundaries that are to be used in passive data connections. The string should contain two numbers separated by a space.
$ DEFINE TCPWARE_FTP_SERVER_DATA_PORT_RANGE 5000 7000
By setting the logical name TCPWARE_FTP_SERVER_LOG_LIMIT in the LOGIN.COM file, you can specify that log files be retained. Set the logical name to a dash (-) to retain all log files or specify a number in the range of 1 to 32000.
Directory size restrictions limit the number of potential files that can be created. If you do not specify a number or value, one log file is created or overwritten for each FTP session. Use the DCL PURGE command to delete unneeded log files. The following example specifies that 42 log files be retained:
$ DEFINE TCPWARE_FTP_SERVER_LOG_LIMIT 42
|
Note: If the TCPWARE_FTP_SERVER_LOG_LIMIT logical is not defined in a user’s login.com, the system manager can make this a system-wide logical with the syntax:
$ DEFINE/SYSTEM/EXEC TCPWARE_FTP_SERVER_LOG_LIMIT 42
|
The server normally compares the IP network address value specified in the PORT command with the IP network address of the IP address that it is receiving commands from. If these are not in agreement, the PORT command is not accepted. Some multi-homed clients, and clients that can do third party transfers send values that do not match. Defining this logical allows the PORT command to be accepted for these clients by disabling this check. The ? in the logical represents where defined values go. Defined value can be either alpha or numeric.
$ DEFINE TCPWARE_FTP_SERVER_RELAXED_PORT_COMMAND ?
If this logical is defined to True, and TCPWARE_FTP_username_ROOT or TCPWARE_FTP_ROOT are defined, then the default directory is set to the specified root directory before the FTP server is started.
The logical name TCPWARE_FTP_STRIP_VERSION causes VMS mode output to have no version numbers if TCPWARE_FTP_ALL_VERSIONS has been defined as FALSE.
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_STRIP_VERSION FALSE
If the FTP server is in UNIX mode, the SYST command displays the banner “UNIX TCPware Unix Emulation”. If the FTP server is in VMS mode, the SYST command displays the equivalence string associated with the TCPWARE_FTP_SYST_BANNER logical name (if defined). Otherwise, the SYST command displays “VMS TCPware Vx.y(rev)” where:
· Vx.y is the TCPware version number.
· (rev) is the revision number of the FTP server.
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_SYST_BANNER “TCPware FTP”
|
Note: The logical name TCPWARE_FTP_SYST_BANNER is ignored if the FTP server is already in UNIX mode.
|
If the logical TCPWARE_FTP_STOU_OLDNAM is defined then the FTP server will attempt to preserve the existing file name when doing a store unique operation.
If this logical is defined /system to False then users that come in via TLS are not allowed to change to a clear text command channel. A clear text command channel can be useful so that firewalls can open the necessary ports when the data channel is opened with the PORT, EPRT, PASV, EPSV commands and replies.
If this logical is defined /system to False then users that come in via TLS must set the protection level to private before doing any data transfers. This includes directory commands, append, put and get.
If you define the logical name TCPWARE_FTP_UNIX_STYLE_BY_DEFAULT, the FTP server starts in UNIX emulation mode.
|
Note: This logical should be used in conjunction with TCPWARE_FTP_DISALLOW_UNIX_STYLE to obtain the desired effect.
|
The control of version number displays has been reworked in response to LIST and NLST commands. The default is VMS-mode output.
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_UNIX_STYLE_BY_DEFAULT TRUE
The logical name TCPWARE_FTP_UNIX_STYLE_CASE_INSENSITIVE allows UNIX style filename handling to be case insensitive.
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_UNIX_STYLE_CASE_INSENSITIVE TRUE
The FTP server displays the creation month, day, and year of a file for a UNIX mode directory if the file is older than 1 year (365 days). If the logical TCPWARE_FTP_UNIX_YEAR_OLD_FILES is defined False, the old behavior is restored, displaying all files with Month, Day, and Time.
The logical TCPWARE_FTP_USE_SRI_ENCODING_ON_ODS5 can be defined to TRUE to cause the file name encoding used for UNIX-style file names on ODS-2 disks to be used on ODS-5 disks. This also sets the default case of letters in filenames to lowercase and ignores the stored case.
The FTP client and the FTP server set the TCP window size of the data connection to either:
· The value of the TCPWARE_FTP_WINDOW logical if you define it (the minimum value is 512 bytes, the maximum value is 1,048,576 bytes).
· The larger of 32,768 bytes and the default TCP window size.
$ DEFINE/SYSTEM/NOLOG/EXEC TCPWARE_FTP_WINDOW 8192
The following logicals can be defined before starting FTP (or TCPware) to control the quotas that are used by the FTP listener and server.
· TCPWARE_FTP_SERVER_WSLIMIT
· TCPWARE_FTP_SERVER_WSQUOTA
· TCPWARE_FTP_SERVER_WSEXTENT
· TCPWARE_FTP_SERVER_PAGEFILE
· TCPWARE_FTP_SERVER_TQELM
· TCPWARE_FTP_SERVER_ENQLM
· TCPWARE_FTP_SERVER_ASTLM
· TCPWARE_FTP_SERVER_PRCLM
· TCPWARE_FTP_SERVER_BYTLM
· TCPWARE_FTP_SERVER_FILLM
· TCPWARE_FTP_SERVER_DIOLM
· TCPWARE_FTP_SERVER_BIOLM
This section describes the FTP server implementation of the File Transfer Protocol (FTP) as defined in the RFC 959, RFC 2228, RFC 2428 and RFC 4217. The material in this section requires a thorough understanding of the protocols used.
The FTP server is “UNIX friendly” and accommodates pathname specifications in some Web browsers; the forward slash (/) at the beginning of directory structures is recognized.
The FTP server implements the following FTP service commands defined in the FTP protocol:
|
ACCT arguments |
TCPware ignores this command but acknowledges it with successful completion. |
|
ALLO arguments |
If specified before a STOR operation, rounds up the size (in bytes) specified with ALLO to the number of blocks and uses it as the initial allocation. If the size specified with ALLO is negative, the allocation is contiguous. |
|
APPE filespec |
Appends the data received from the requesting host to the specified file (if the file does not exist, TCPware creates it). |
|
AUTH TLS |
Requests TLS authentication be used for user authentication as specified in RFC 4217. |
|
CCC |
Requests that the command channel return to clear text as specified in RFC 2228 and RFC 4217. |
|
CDUP |
Sets the default working directory to the parent directory for the current directory. XCUP is a synonym. |
|
CWD directory |
Specifies the new default working directory. XCWD is a synonym. |
|
DELE filespec |
Deletes the file (or files) specified. |
|
EPRT argument |
Specifies the data port number used for data transfers as per RFC 2428. Only IPv4 addresses are allowed. The FTP server reports a 501 Bad parameter value error if a port less than 1024 is specified. If you want to use a privileged port for the destination of data transfer, define the following logical to disable this feature:
$ DEFINE/SYSTEM TCPWARE_FTPD_ALLOW_PRIV_PORT “TRUE”
The code also checks that the IP address is the same as the client FTP address. When TLS is not in use this can be overridden by defining the logical TCPWARE_FTP_SERVER_RELAXED_PORT_COMMAND. |
|
EPSV argument |
Requests the server data transfer process to be passive as per RFC 2428. This means to "listen" on a non-default data port and wait for a connection instead of initiating one upon receiving a transfer command. The server responds with the host name and port number on which it is listening. |
|
FEAT |
Lists the available features (optional commands) that the FTP server includes support for. |
|
HELP [topic] |
Requests help information. |
|
LIST filespec |
Returns a directory listing. |
|
MDTM filespec |
Returns the modification time of the file in UTC as YYYYMMDDHHMMSS. |
|
MKD filespec |
Creates the specified directory. XMKD is a synonym. |
|
MODE arguments |
Specifies the transfer mode. The valid arguments are S (STREAM), C (COMPRESSED) and Z (DEFLATE). |
|
NLST filespec |
Returns a list of file names without a .DIR extension if the client is not an OpenVMS machine. Retrieving a directory file (*.DIR) if the client is not an OpenVMS machine results in an error message. |
|
NOOP |
TCPware ignores this command but acknowledges it with successful completion. |
|
OPTS parameters |
Set optional parameters for features that support them. The only feature that currently supports options is MODE Z which can have the LEVEL parameter for the ZLIB engine set to -1 to 9. -1 is the default which gives a balance of compression and CPU time usage, 0 (zero) is no compression, and 9 is maximum compression. Other options (ENGINE, METHOD, EXTRA and BLOCKSIZE) documented in draft-preson-ftpext-deflate-04 are not implemented as they do not apply to the ZLIB deflate engine. |
|
PASS password |
Logs the user into the host. If the first character of the password is a hyphen (-), the default successful login (230) message appears. The optional messages defined by the TCPWARE_FTP_230_REPLY or TCPWARE_FTP_ANONYMOUS_230_REPLY logicals do not appear. This supports clients that cannot receive the multi-line replies these logicals can generate. |
|
PASV |
Requests the server data transfer process to be passive. This means to "listen" on a non-default data port and wait for a connection instead of initiating one upon receiving a transfer command. The server responds with the host name and port number on which it is listening. |
|
PBSZ size |
Specifies the protection buffer size as described in RFC 2228 and RFC 4217. The only size allowed by RFC 4217 is 0 (zero). |
|
PORT arguments |
Specifies the data port number used for data transfers. The FTP server reports a 501 Bad parameter value error if a port less than 1024 is specified. If you want to use a privileged port for the destination of data transfer, define the following logical to disable this feature:
$ DEFINE/SYSTEM TCPWARE_FTPD_ALLOW_PRIV_PORT “TRUE”
The code also checks that the IP address is the same as the client FTP address. When TLS is not in use this can be overridden by defining the logical TCPWARE_FTP_SERVER_RELAXED_PORT_COMMAND. |
|
PROT level |
Specifies the protection level as described in RFC 2228 and RFC 4217. The only protection levels allowed by RFC 4217 are C and P. The server does not allow the protection level to be changed after the command channel has been set to clear text mode. |
|
PWD |
Returns the current working directory. XPWD is a synonym. |
|
QUIT |
Closes the connection. |
|
REIN |
Logs out the user and resets the file transfer parameters to the initial values. |
|
RETR filespec |
Reads the file and transmits it to the requesting host. |
|
RMD filespec |
Deletes the specified directory if the directory is empty. XRMD is a synonym. An error reply is sent if the directory is not empty. |
|
RNFR filespec |
Specifies the file to be renamed. |
|
RNTO filespec |
Specifies the new name of the file designated in the RNFR command. |
|
SITE arguments |
Used for site-specific requirements or capabilities. The following SITE commands are supported:
SITE HELP - Returns a list of supported SITE commands. SITE PRIV [privileges] - Turns process privileges on or off. The arguments are ALL, NONE, or a privilege name. With no arguments, SITE PRIV displays the current process privileges. SITE RMS RECSIZE [value] - Controls the record size used when writing binary files; any valid RMS record size value is permitted. With no arguments, displays the current value. Applies only when STREAM is OFF. The default is 512. SITE SHOW TIME - Returns the current date and time-of-day for the OpenVMS system in the reply message. SITE SPAWN command-line - A subprocess executes the specified command line. Use this command for submitting batch jobs and printing files. The status returned for the SITE command depends on the status returned by the utility or command executed (see the VMS documentation regarding the DCL $STATUS symbol). SITE +VMS+ - Receiving this command from an HP TCP/IP Services for OpenVMS (UCX) client sets the file transfer mode to VMS_PLUS. WINDOW_SIZE - Displays or sets the TCP window size. |
|
SIZE filespec |
Returns the size in bytes of the file specified. |
|
STOR filespec |
Writes the
file from data received from the requesting host. The STORE
command supports the /ASCII, /BINARY, /BLOCK, |
|
STOU filespec |
Writes the data received from the requesting host to a unique filename. If you specify a filespec, TCPware uses it as the seed for the unique filename; otherwise, the server creates a unique filename. The STOU command uses a data connection. |
|
Note: The STOU filespec pathname can contain the /ASCII, /BINARY, /BLOCK, /FORTRAN, or /IMAGE qualifier to specify the transfer mode. A qualifier can cause unpredictable results depending on the current TYPE and STRU settings. The pathname can also contain /CONTIGUOUS=blocks, in which case TCPware creates the file with an initial contiguous allocation of the specified number of blocks.
|
|
STRU arguments |
Specifies the file structure. The valid arguments are F (for file, or no record structure), R (for record structure), and O VMS (or VMS, for VMS file structure). For VMS file structure, the data sent over the connection consists of a small header containing RMS file information, followed by raw data from the file, block by block. |
|
SYST |
Returns the name of the operating system running on the server. |
|
TYPE arguments |
Specifies the file type. The valid arguments are A (ASCII), I (image), L 8 (image), A N (ASCII non-print), A C (FORTRAN carriage control), and A T (Telnet format effectors). Use I (image) for both formatted binary and image format transfers. Formatted binary data includes the necessary record headers and checksums. |
|
USER name |
Logs the user into the host. |
All other commands result in error 500 or 502 (command not implemented). This implementation accepts and may issue all response codes.
If you want the device name, the file name, and the directory name included in the results of all NLST commands, define the logical TCPWARE_FTP_INCLUDE_DEVICE_IN_NLST. This logical may be declared system wide or in the user’s LOGIN.COM file.
The FTP service corrects a problem with RENAME operations with UNIX-style file specifications. The RENAME operation overrides the current protection of the file to do the operation and then restores it afterwards. This is necessary because directories are created such that they cannot be deleted without changing the protection. To cause RENAME to observe the file protection, define the logical TCPWARE_FTP_OBSERVE_VMS_PROTECTION to true.
The FTP server accepts the following qualifiers with client commands that send RETR, STOR, and APPE commands:
|
Note: When using the /ASCII, /BINARY, /BLOCK, /FORTRAN, or /IMAGE qualifier with commands that send RETR or STOR commands, make sure to separate the file specification and the qualifier with a space character. Otherwise, the qualifier can be considered part of a UNIX file specification. For example, use the following on the client:
ftp>put sample.txt "sample.txt /block"
|
|
/ASCII |
TCPware reads or writes the file as an ASCII file. |
|
/BINARY |
TCPware reads or writes the file as a formatted binary file. Use this qualifier when transferring variable length binary files that do not have a file extension of .OBJ, .STB, .BIN, or .LDA. |
|
/BLOCK |
TCPware reads or writes the file using block-I/O mode. Use this qualifier when transferring STREAM_LF, STREAM_CR, STREAM or UNDEFINED files. |
|
/CONTIGUOUS |
(Applies to STOR only) the local output file should have an initial contiguous allocation of the specified number of blocks. If the output file is smaller, the FTP server truncates it. If the output file is larger, the additional allocations are noncontiguous. |
|
/FORTRAN |
TCPware reads or writes the file as a FORTRAN carriage control file. |
|
/IMAGE[=n] |
TCPware reads or writes the file as an image file. If you specify a record length, it only applies to output files. |
|
/VARIABLE |
TCPware writes an image format file as a variable length record format file. Ignored for all other transfer formats. |
The FTP server also supports the STRU O VMS (or STRU VMS) format that allows OpenVMS systems to exchange any RMS file, including RMS indexed files.
|
Note: Some combinations of these qualifiers and the TYPE and STRU commands may produce unpredictable results. Use these qualifiers carefully.
|
Q: How can I apply Access Control Lists (ACLs) to my FTP executables so that only I have access?
A: Assume you want to set up your username as FTP_USER and give yourself (and no one else) read and execute privileges to the FTP executables:
$ SET
DEFAULT$SYSTEM
$ MCR AUTHORIZE
UAF>ADD/ID FTP_USER
UAF>GRANT/ID FTP_USER yourname
Then, for the FTP client:
$ SET
DEFAULT TCPWARE
$ EDIT/ACL FTP.EXE
(IDENTIFIER=FTP_USER,ACCESS=READ+EXECUTE)
(IDENTIFIER=*,ACCESS=NONE)
Ctrl+Z
For the FTP server:
$ SET
DEFAULT TCPWARE
$ EDIT/ACL FTP_DTP.EXE
(IDENTIFIER=FTP_USER,ACCESS=READ+EXECUTE)
(IDENTIFIER=*,ACCESS=NONE)
Ctrl+Z