1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin ftpd n 1.2.5] 3[moddesc {Tcl FTP Server Package}] 4[titledesc {Tcl FTP server implementation}] 5[category Networking] 6[require Tcl 8.3] 7[require ftpd [opt 1.2.5]] 8[description] 9 10The [package ftpd] package provides a simple Tcl-only server library 11for the FTP protocol as specified in 12RFC 959 ([uri http://www.rfc-editor.org/rfc/rfc959.txt]). 13It works by listening on the standard FTP socket. Most server errors 14are returned as error messages with the appropriate code attached to 15them. Since the server code for the ftp daemon is executed in the 16event loop, it is possible that a 17 18[cmd bgerror] will be thrown on the server if there are problems with 19the code in the module. 20 21[section COMMANDS] 22 23[list_begin definitions] 24 25[call [cmd ::ftpd::server] [opt [arg myaddr]]] 26 27Open a listening socket to listen to and accept ftp connections. 28myaddr is an optional argument. [arg myaddr] is the domain-style name 29or numerical IP address of the client-side network interface to use 30for the connection. 31 32[call [cmd ::ftpd::config] [opt [arg {option value}]] [opt [arg {option value ...}]]] 33 34The value is always the name of the command to call as the 35callback. The option specifies which callback should be configured. 36See section [sectref CALLBACKS] for descriptions of the arguments and 37return values for each of the callbacks. 38 39[list_begin definitions] 40 41[def "-authIpCmd [arg proc]"] 42 43Callback to authenticate new connections based on the ip-address of 44the peer. 45 46[def "-authUsrCmd [arg proc]"] 47 48Callback to authenticate new connections based on the user logging in 49(and the users password). 50 51[def "-authFileCmd [arg proc]"] 52 53Callback to accept or deny a users access to read and write to a 54specific path or file. 55 56[def "-logCmd [arg proc]"] 57 58Callback for log information generated by the FTP engine. 59 60[def "-fsCmd [arg proc]"] 61 62Callback to connect the engine to the filesystem it operates on. 63 64[def "-closeCmd [arg proc]"] 65 66Callback to be called when a connection is closed. This allows the 67embedding application to perform its own cleanup operations. 68 69[def "-xferDoneCmd [arg proc]"] 70 71Callback for transfer completion notification. In other words, it is 72called whenever a transfer of data to or from the client has 73completed. 74 75[list_end] 76[list_end] 77 78 79[section CALLBACKS] 80 81[list_begin definitions] 82 83[def "[cmd authIpCmd] callback"] 84 85The authIpCmd receives the ip-address of the peer attempting to 86connect to the ftp server as its argument. It returns a 1 to allow 87users from the specified IP to attempt to login and a 0 to reject the 88login attempt from the specified IP. 89 90[def "[cmd authUsrCmd] callback"] 91 92The authUsrCmd receives the username and password as its two 93arguments. It returns a 1 to accept the attempted login to the ftpd 94and a 0 to reject the attempted login. 95 96[def "[cmd authFileCmd] callback"] 97 98The authFileCmd receives the user (that is currently logged in), the 99path or filename that is about to be read or written, and 100 101[const read] or [const write] as its three arguments. It returns a 1021 to allow the path or filename to be read or written, and a 0 to 103reject the attempted read or write with a permissions error code. 104 105[def "[cmd logCmd] callback"] 106 107The logCmd receives a severity and a message as its two arguments. 108The severities used within the ftpd package are [const note], 109 110[const debug], and [const error]. The logCmd doesn't return 111anything. 112 113[def "[cmd fsCmd] callback"] 114 115The fsCmd receives a subcommand, a filename or path, and optional 116additional arguments (depending on the subcommand). 117 118[para] 119The subcommands supported by the fsCmd are: 120 121[list_begin definitions] 122 123[call [arg fsCmd] [method append] [arg path]] 124 125The append subcommand receives the filename to append to as its 126argument. It returns a writable tcl channel as its return value. 127 128[call [arg fsCmd] [method delete] [arg path] [arg channel]] 129 130The delete subcommand receives the filename to delete, and a channel 131to write to as its two arguments. The file specified is deleted and 132the appropriate ftp message is written to the channel that is passed 133as the second argument. The delete subcommand returns nothing. 134 135[call [arg fsCmd] [method dlist] [arg path] [arg style] [arg channel]] 136 137The dlist subcommand receives the path that it should list the files 138that are in, the style in which the files should be listed which is 139either [const nlst] or [const list], and a channel to write to as 140its three arguments. The files in the specified path are printed to 141the specified channel one per line. If the style is [const nlst] 142only the name of the file is printed to the channel. If the style is 143[const list] then the file permissions, number of links to the file, 144the name of the user that owns the file, the name of the group that 145owns the file, the size (in bytes) of the file, the modify time of the 146file, and the filename are printed out to the channel in a formatted 147space separated format. The [method dlist] subcommand returns 148nothing. 149 150[call [arg fsCmd] [method exists] [arg path]] 151 152The exists subcommand receives the name of a file to check the 153existence of as its only argument. The exists subcommand returns a 1 154if the path specified exists and the path is not a directory. 155 156[call [arg fsCmd] [method mkdir] [arg path] [arg channel]] 157 158The mkdir subcommand receives the path of a directory to create and a 159channel to write to as its two arguments. The mkdir subcommand 160creates the specified directory if necessary and possible. The mkdir 161subcommand then prints the appropriate success or failure message to 162the channel. The mkdir subcommand returns nothing. 163 164[call [arg fsCmd] [method mtime] [arg path] [arg channel]] 165 166The mtime subcommand receives the path of a file to check the modify 167time on and a channel as its two arguments. If the file exists the 168mtime is printed to the channel in the proper FTP format, otherwise an 169appropriate error message and code are printed to the channel. The 170mtime subcommand returns nothing. 171 172[call [arg fsCmd] [method permissions] [arg path]] 173 174The permissions subcommand receives the path of a file to retrieve the 175permissions of. The permissions subcommand returns the octal file 176permissions of the specified file. The file is expected to exist. 177 178[call [arg fsCmd] [method rename] [arg path] [arg newpath] [arg channel]] 179 180The rename subcommand receives the path of the current file, the new 181file path, and a channel to write to as its three arguments. The 182rename subcommand renames the current file to the new file path if the 183path to the new file exists, and then prints out the appropriate 184message to the channel. If the new file path doesn't exist the 185appropriate error message is printed to the channel. The rename 186subcommand returns nothing. 187 188[call [arg fsCmd] [method retr] [arg path]] 189 190The retr subcommand receives the path of a file to read as its only 191argument. The retr subcommand returns a readable channel that the 192specified file can be read from. 193 194[call [arg fsCmd] [method rmdir] [arg path] [arg channel]] 195 196The rmdir subcommand receives the path of a directory to remove and a 197channel to write to as its two arguments. The rmdir subcommand 198removes the specified directory (if possible) and prints the 199appropriate message to the channel (which may be an error if the 200specified directory does not exist or is not empty). The rmdir 201subcommand returns nothing. 202 203[call [arg fsCmd] [method size] [arg path] [arg channel]] 204 205The size subcommand receives the path of a file to get the size (in 206bytes) of and a channel to write to as its two arguments. The size 207subcommand prints the appropriate code and the size of the file if the 208specified path is a file, otherwise an appropriate error code and 209message are printed to the channel. The size subcommand returns 210nothing. 211 212[call [arg fsCmd] [method store] [arg path]] 213 214The store subcommand receives the path of a file to write as its only 215argument. The store subcommand returns a writable channel. 216 217[list_end] 218 219 220[def "[cmd closeCmd]"] 221 222The [cmd closeCmd] receives no arguments when it is invoked, and any 223return value it may generate is discarded. 224 225[def "[cmd xferDoneCmd] sock sock2 file bytes filename err"] 226 227The [cmd xferDoneCmd] receives six arguments when invoked. These are, 228in this order, the channel handle of the control socket for the 229connection, the channel handle of the data socket used for the 230transfer (already closed), the handle of the channel containing the 231transfered file, the number of bytes transfered, the path of the file 232which was transfered, and a (possibly empty) error message. 233 234Any return value it may generate is discarded. 235 236[list_end] 237 238 239[section VARIABLES] 240 241[list_begin definitions] 242 243[def [var ::ftpd::cwd]] 244 245The current working directory for a session when someone first 246connects to the FTPD or when the [cmd REIN] ftp command is received. 247 248[def [var ::ftpd::contact]] 249 250The e-mail address of the person that is the contact for the ftp 251server. This address is printed out as part of the response to the 252[cmd {FTP HELP}] command. 253 254[def [var ::ftpd::port]] 255 256The port that the ftp server should listen on. 257If port is specified as zero, the operating system will allocate an 258unused port for use as a server socket; afterwards, the variable will 259contain the port number that was allocated. 260 261[def [var ::ftpd::welcome]] 262 263The message that is printed out when the user first connects to the 264ftp server. 265 266 267[def [var ::ftpd::CurrentSocket]] 268 269Accessible to all callbacks and all filesystem commands (which are a 270special form of callback) and contains the handle of the socket 271channel which was active when the callback was invoked. 272 273[list_end] 274 275[section {BUGS, IDEAS, FEEDBACK}] 276 277This document, and the package it describes, will undoubtedly contain 278bugs and other problems. 279 280Please report such in the category [emph ftpd] of the 281[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 282 283Please also report any ideas for enhancements you may have for either 284package and/or documentation. 285 286 287[keywords ftpd ftp ftpserver services {rfc 959}] 288[manpage_end] 289