ftpd(n)                     Tcl FTP Server Package                     ftpd(n)



______________________________________________________________________________

NAME
       ftpd - Tcl FTP server implementation

SYNOPSIS
       package require Tcl  8.3

       package require ftpd  ?1.2.5?

       ::ftpd::server ?myaddr?

       ::ftpd::config ?option value? ?option value ...?

       fsCmd append path

       fsCmd delete path channel

       fsCmd dlist path style channel

       fsCmd exists path

       fsCmd mkdir path channel

       fsCmd mtime path channel

       fsCmd permissions path

       fsCmd rename path newpath channel

       fsCmd retr path

       fsCmd rmdir path channel

       fsCmd size path channel

       fsCmd store path

_________________________________________________________________

DESCRIPTION
       The ftpd package provides a simple Tcl-only server library for the FTP
       protocol as specified in RFC 959 (http://www.rfc-
       editor.org/rfc/rfc959.txt).  It works by listening on the standard FTP
       socket.  Most server errors are returned as error messages with the
       appropriate code attached to them.  Since the server code for the ftp
       daemon is executed in the event loop, it is possible that a bgerror
       will be thrown on the server if there are problems with the code in the
       module.

COMMANDS
       ::ftpd::server ?myaddr?
              Open a listening socket to listen to and accept ftp connections.
              myaddr is an optional argument.  myaddr is the domain-style name
              or numerical IP address of the client-side network interface to
              use for the connection.

       ::ftpd::config ?option value? ?option value ...?
              The value is always the name of the command to call as the
              callback. The option specifies which callback should be
              configured.  See section CALLBACKS for descriptions of the
              arguments and return values for each of the callbacks.

              -authIpCmd proc
                     Callback to authenticate new connections based on the ip-
                     address of the peer.

              -authUsrCmd proc
                     Callback to authenticate new connections based on the
                     user logging in (and the users password).

              -authFileCmd proc
                     Callback to accept or deny a users access to read and
                     write to a specific path or file.

              -logCmd proc
                     Callback for log information generated by the FTP engine.

              -fsCmd proc
                     Callback to connect the engine to the filesystem it
                     operates on.

              -closeCmd proc
                     Callback to be called when a connection is closed. This
                     allows the embedding application to perform its own
                     cleanup operations.

              -xferDoneCmd proc
                     Callback for transfer completion notification. In other
                     words, it is called whenever a transfer of data to or
                     from the client has completed.

CALLBACKS
       authIpCmd callback
              The authIpCmd receives the ip-address of the peer attempting to
              connect to the ftp server as its argument. It returns a 1 to
              allow users from the specified IP to attempt to login and a 0 to
              reject the login attempt from the specified IP.

       authUsrCmd callback
              The authUsrCmd receives the username and password as its two
              arguments. It returns a 1 to accept the attempted login to the
              ftpd and a 0 to reject the attempted login.

       authFileCmd callback
              The authFileCmd receives the user (that is currently logged in),
              the path or filename that is about to be read or written, and
              read or write as its three arguments.  It returns a 1 to allow
              the path or filename to be read or written, and a 0 to reject
              the attempted read or write with a permissions error code.

       logCmd callback
              The logCmd receives a severity and a message as its two
              arguments.  The severities used within the ftpd package are
              note, debug, and error. The logCmd doesn't return anything.

       fsCmd callback
              The fsCmd receives a subcommand, a filename or path, and
              optional additional arguments (depending on the subcommand).

              The subcommands supported by the fsCmd are:

              fsCmd append path
                     The append subcommand receives the filename to append to
                     as its argument. It returns a writable tcl channel as its
                     return value.

              fsCmd delete path channel
                     The delete subcommand receives the filename to delete,
                     and a channel to write to as its two arguments.  The file
                     specified is deleted and the appropriate ftp message is
                     written to the channel that is passed as the second
                     argument.  The delete subcommand returns nothing.

              fsCmd dlist path style channel
                     The dlist subcommand receives the path that it should
                     list the files that are in, the style in which the files
                     should be listed which is either nlst or list, and a
                     channel to write to as its three arguments.  The files in
                     the specified path are printed to the specified channel
                     one per line.  If the style is nlst only the name of the
                     file is printed to the channel.  If the style is list
                     then the file permissions, number of links to the file,
                     the name of the user that owns the file, the name of the
                     group that owns the file, the size (in bytes) of the
                     file, the modify time of the file, and the filename are
                     printed out to the channel in a formatted space separated
                     format.  The dlist subcommand returns nothing.

              fsCmd exists path
                     The exists subcommand receives the name of a file to
                     check the existence of as its only argument.  The exists
                     subcommand returns a 1 if the path specified exists and
                     the path is not a directory.

              fsCmd mkdir path channel
                     The mkdir subcommand receives the path of a directory to
                     create and a channel to write to as its two arguments.
                     The mkdir subcommand creates the specified directory if
                     necessary and possible.  The mkdir subcommand then prints
                     the appropriate success or failure message to the
                     channel.  The mkdir subcommand returns nothing.

              fsCmd mtime path channel
                     The mtime subcommand receives the path of a file to check
                     the modify time on and a channel as its two arguments.
                     If the file exists the mtime is printed to the channel in
                     the proper FTP format, otherwise an appropriate error
                     message and code are printed to the channel.  The mtime
                     subcommand returns nothing.

              fsCmd permissions path
                     The permissions subcommand receives the path of a file to
                     retrieve the permissions of.  The permissions subcommand
                     returns the octal file permissions of the specified file.
                     The file is expected to exist.

              fsCmd rename path newpath channel
                     The rename subcommand receives the path of the current
                     file, the new file path, and a channel to write to as its
                     three arguments.  The rename subcommand renames the
                     current file to the new file path if the path to the new
                     file exists, and then prints out the appropriate message
                     to the channel.  If the new file path doesn't exist the
                     appropriate error message is printed to the channel.  The
                     rename subcommand returns nothing.

              fsCmd retr path
                     The retr subcommand receives the path of a file to read
                     as its only argument.  The retr subcommand returns a
                     readable channel that the specified file can be read
                     from.

              fsCmd rmdir path channel
                     The rmdir subcommand receives the path of a directory to
                     remove and a channel to write to as its two arguments.
                     The rmdir subcommand removes the specified directory (if
                     possible) and prints the appropriate message to the
                     channel (which may be an error if the specified directory
                     does not exist or is not empty).  The rmdir subcommand
                     returns nothing.

              fsCmd size path channel
                     The size subcommand receives the path of a file to get
                     the size (in bytes) of and a channel to write to as its
                     two arguments.  The size subcommand prints the
                     appropriate code and the size of the file if the
                     specified path is a file, otherwise an appropriate error
                     code and message are printed to the channel.  The size
                     subcommand returns nothing.

              fsCmd store path
                     The store subcommand receives the path of a file to write
                     as its only argument.  The store subcommand returns a
                     writable channel.

       closeCmd
              The closeCmd receives no arguments when it is invoked, and any
              return value it may generate is discarded.

       xferDoneCmd sock sock2 file bytes filename err
              The xferDoneCmd receives six arguments when invoked. These are,
              in this order, the channel handle of the control socket for the
              connection, the channel handle of the data socket used for the
              transfer (already closed), the handle of the channel containing
              the transfered file, the number of bytes transfered, the path of
              the file which was transfered, and a (possibly empty) error
              message.  Any return value it may generate is discarded.

VARIABLES
       ::ftpd::cwd
              The current working directory for a session when someone first
              connects to the FTPD or when the REIN ftp command is received.

       ::ftpd::contact
              The e-mail address of the person that is the contact for the ftp
              server.  This address is printed out as part of the response to
              the FTP HELP command.

       ::ftpd::port
              The port that the ftp server should listen on.  If port is
              specified as zero, the operating system will allocate an unused
              port for use as a server socket; afterwards, the variable will
              contain the port number that was allocated.

       ::ftpd::welcome
              The message that is printed out when the user first connects to
              the ftp server.

       ::ftpd::CurrentSocket
              Accessible to all callbacks and all filesystem commands (which
              are a special form of callback) and contains the handle of the
              socket channel which was active when the callback was invoked.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category ftpd of
       the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report
       any ideas for enhancements you may have for either package and/or
       documentation.

KEYWORDS
       ftp, ftpd, ftpserver, rfc 959, services

CATEGORY
       Networking



ftpd                                 1.2.5                             ftpd(n)
