


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.4?

       ::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-edi-
       tor.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



ftpd                          1.2.4                             1





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


              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 call-
              back. 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 oper-
                     ates 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



ftpd                          1.2.4                             2





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


              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  argu-
              ments.   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 argu-
                     ment.  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



ftpd                          1.2.4                             3





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


                     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 cur-
                     rent 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 chan-
                     nel  (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 appropri-
                     ate code and the size of the file if the  specified  path
                     is  a  file, otherwise an appropriate error code and mes-
                     sage 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.



ftpd                          1.2.4                             4





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


       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 mes-
              sage.  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 spec-
              ified as zero, the operating system will allocate an unused port
              for  use  as a server socket; afterwards, the variable will con-
              tain 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://source-
       forge.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.4                             5


