User Language Programs as FTP Clients

1. User Language Programs as FTP Clients Tom Thoresen

2. Agenda • FTP Summary • Port Definitions • Access Control • FTP Requests and Responses • Coding Examples (Sockets API)

3. FTP Summary • First proposal written in 1971 • Current RFC is 959 • http://www.faqs.org/rfcs/rfc959.html • Implemented on many diverse platforms • An essential tool for modern networks • Mostly because it is so widely implemented – Everyone’s got one • Two TCP connections required to effect file transfer • Control connection (using Telnet protocol) • Data connection • Unique protocol in this regard

4. FTP Summary • Really a peer to peer protocol until introduction of PASV (passive) command • Both client and server actively open TCP connections • PASV command support required for our examples • Almost every modern FTP server supports it • And ours will, too -- soon

5. Janus Port Definition • Establish valid FTP server locations • IP addresses, subnets, port numbers • FTP Servers use well-known port number 21 • Host names (with wildcard matching) • Number of concurrent threads • Limited by MAXCON which is set by Sirius’ auth zap • Limits on number of sockets per thread • Default is 1

6. Janus Port Definition • JANUS DEFINE FTPCLIENT * CLSOCK 5 REMOTE * * SOCKPMAX 2 • Single port definition • Both control and data connections will use the same port • SOCKPMAX must be explicitly set since each client thread will use two TCP connections • May slow debugging if using trace with x’08’ bit • Each $SOCK_CONN call must explicitly name host and port number • REMOTE can be more specific, a pattern, or a subnet to limit valid hosts

7. Janus Port Definition JANUS DEFINE FTPCTL * CLSOCK 5 REMOTE 198.242.244.9 21 JANUS DEFINE FTPDAT * CLSOCK 5 REMOTE 198.242.244.9 * • Dual port definition • Separate port for control and data connections • Must use data port number of * since port number is unknown until control connection is made • $SOCK_CONN calls may need only port name to connect • Applications don’t need to know the host name or IP address if remote is explicit • Use $SOCK_INFO to get IP address for data connection

8. Access Control • Specify access control for Janus FTP client ports • User or user group • Procedure name • Procedure file name • APSY Subsystem • IPGROUP

9. Access Control • JANUS CLSOCK FTPC* ALLOW NONE • JANUS CLSOCK FTPC* ALLOW USGROUP FTPERS • JANUS CLSOCK FTPC* ALLOW SUBSYS FTPAPSY • Allow Rule specification (familiar to Janus Web customers) • Which users are allowed to open sockets on the port(s) specified • System administrators can always open sockets on any available port • They can control ports definitions, so no sense in restricting them • USGROUPS defined by JANUS DEFUSG / JANUS DELUSG command • Note that the first rule clears all other existing rules

10. Sending FTP Requests • A verb followed by an optional parameter • Via Telnet connection with FTP server • Requests and responses delimited with CRLF sequence • Verbs are always character data • Verbs are case-insensitive – but send in upper case • Use ‘PUSH’ option on $SOCK_SEND when sending commands • Otherwise connection may timeout waiting on data socket

11. FTP Server Responses • One or more CR LF delimited ‘lines’ in a response • Code followed by a hyphen or blank • Hyphen indicates more lines in response 221-You have transferred 10092 bytes in 1 files. 221-Total traffic for this session was 10493 bytes in 1 transfers. 221-Thank you for using the FTP service on lin875.sirius-software.com. 221 Goodbye. • Blank following code indicates last line in response • Any text after return code is intended simply for display (one exception…)

12. FTP Server Responses • Code indicates success or failure of request • Text following code suitable for printing or logging • Code meanings: • 100-199 informational • 200-299 greetings (sign-on, signoff) • 300-399 accounting • 400-599 errors (permanent or temporary) • Simple command and response makes writing server or client fairly easy

13. PASV Request • PASV verb added to FTP spec to allow client to initiate data transfer • Violates normal command structure • Client must parse the response for IP and port • Janus FTP clients require PASV support • Can’t LISTEN for incoming connections • Almost all modern FTP support it (we will soon) • Response from PASV request • Contains IP address and port for data connection

14. Sample FTP Client • Make the control connection to the FTP server • %sock = $SOCK_CONN(%port, %host, %pnum) • Port is the name of the Janus port (not a port number) • Host must be specified if Janus port specification is not explicit • ex. ‘REMOTE 198.242.244.0-24’ • Pnum is the TCP port number (usually 21) • Again not necessary if Janus port definition explicitly specifies port number • Positive return value indicates success • Most negative values indicate ‘permanent’ error, but –104 or –106 might be retried successfully

15. Sample FTP Client • Set PRSTOK value • Tells $SOCK_RECVPRS what terminates a ‘line’ • %rc = $SOCK_SET(%sock, 'PRSTOK', '0D0A') • CR LF pair always terminates an FTP command or response • Define RESET handler • Label in same or lower scope within UL procedure • Place to ‘bail out’ when things go awry • %rc = $SOCK_ONRESET('CTLRESET') • For our FTP client, if either socket is reset, the code will be executed

16. Sample FTP Client • Read the initial greeting from the FTP server • Servers always send a ‘greeting’ using return code 2xx • Return code 4xx means we’ve been brushed off by the server, possibly it’s too busy to handle new connections • %rc = $SOCK_RECVPRS(%sock, %resp, -1) • Login • Send the USER command with the username • The server may accept the login (return code of 230) • Or indicate that a password is required (return code of 33x) • Rarely, a server may ask for ACCT by returning 33x from PASS • This is unusual, and our sample does not ‘account’ for this

17. Sample FTP Client • Get the data connection info • Send the PASV request • Server will respond with code 500 if PASV unsupported • Or 227 followed by the IP address of the server and the data port number • Port number is a 16 bit unsigned binary number expressed as 2 comma separated decimal values, most significant byte first • Ex. 205,180 = 205*256+180 = 46331 • 227 is the only FTP response that must be parsed 500 'PASV': command not understood. 227 Entering Passive Mode (198,242,244,9,205,180)

18. Sample FTP Client • Get the data connection info … continuation • Don’t use the IP address returned in the PASV command • If the server is behind a NAT firewall it may return an incorrect address • Use $SOCK_INFO to get the IP address of the server • Control and data ports IP addresses can not differ • Or use a dedicated Janus data port so the app needn’t worry about IP addresses at all

19. Sample FTP Client • Open the data connection • Must be done before STOR request is sent, server may start reading immediately after STOR is received • Send the STOR request • Tells the server to start reading from the data connection • Use $SOCK_SEND or $SOCK_SENDLN to send the data • If sending character “TYPE A” data, be sure to add record delimiters to each record. • Read STOR response from control connection • 220-250 all indicate success

20. Sample FTP Client • Send QUIT request • Tells server to close the control connection • Server will respond with 221 message(s) • Close control connection • $SOCK_CLOSE of course • Congratulations!