




                  O P E N F T P D  -  U S E R S   M A N U A L

                              Revision 2001-07-11




                  _____
                 /   _)))
                /   / 6 6
               (   (    \         Hey babe, look at this damn cool
               /  ,' __=          FTPD i found on the internet!
              / __) /_  )        ______________________________________
             ( /   ~  `(                 /
              / / .) .) )     ../////      _____________
             ( /\    (_       \   , ,     |        '\\\\\\
              \| \  '  \       C    \     |        ' ____|_
              :o /      \       \D_/      |   +    '||::::::
               /\    _/  )   ___| (___    |        '||_____|
               \/     )  |  /  \ ~ /  \   \'_______|_____|
                |    /   | /'\  \_/ _' \  ___/____|___\___
             ___|___/\___|(  <_ _____|/_\|    _    '  <<<:|
            /              '-/ \________ |_________'___o_o|
           /                 \~/::::::::|                  \
          /                  '=========='                   \
         /___________________________________________________\
           |                                               |
           |                                               |


NEW: IF YOU USE DEBIAN LINUX CHECKOUT doc/debian.txt TOO!


I. INTRODUCTION

OpenFTPD  is  a  free,  open  source  FTP   server
implementation for the UNIX platform. It is  based
on  FTP4ALL (www.ftp4all.de)  but the  differences         ___
are quite big already.                                    /\/_\_
                                                          \/ ))))
OpenFTPD  was  designed  to  require  no superuser         ",".//
privileges. The advantages  are that it  cannot be         \%_,O
exploited to  gain root  access on  a machine  and           _||___
second,  any  user on  a  UNIX box  can  run  this          /)___/_\
server  without  special  permissions.  The   only         '(_/\_)\/\
restriction  is  that you  can't  use ports  below        />,\\/ / \/\
1024, so you will not  be able to setup a  port 21        \o\/==/\  \/o__
server without being root.                                 (/| /o\\   \,\\-
                                                           //  \ | \
It is not designed to replace wu-ftpd or any other        /o|  |  \ \
system-level FTP server,  neither it does  use the       / /  / o  \ \
default   user database   nor the   UNIX file  and      / /   \    |  \
directory permissions. Instead it sets up its  own     /  | o /    \ o \
user  and group  database and  file and  directory     \  /   |     \   \
permission system.                                     / /   /    o /    \
                                                      / | o  \      )    |
OpenFTPD  is  designed  for  running  a   private,   /__/\___/_____/\___o/
specialised FTP  site with  an own  user and group        ='      ='
database. Although anonymous  FTP is supported  we
don't recommend  this mode  and there  will be  no
further development in this area.


                            II. REQUIREMENTS
          ////)))
          ((((-@-@          To build and install OpenFTPD you need:
           \C    >            - Unix OS (Linux, *BSD or Solaris)
            ;  _=       ____  - Perl (Version 5.005+)
         ___/ /_       / / /  - Digest::MD5 Perl module
    ,_  /  /\~ \ \  _,/-/_/   - glib (Version 1.2+)
 \\\-.\/ ,(__\/_) \/.-///     - Cons (included)
     |  / )  / / \  |         - gcc (or other c compiler)
      \/ /  / (   \/
        /  /\  \
       /   \/   \           III. BUILD
      |____/\___/
       xxxxxxxxx            PERL
       xxxxxxx,
        xxxxx,              Make sure you have  a recent Perl version  and the
         xxxx               Digest::MD5  module   installed.   To   install  a
        / /\ \              missing Digest::MD5 with the CPAN installer type:
        |/  \|              # perl -MCPAN -e 'install Digest::MD5'
        |    |              This  will  install  the  module  to  the  default
       (|    |)             position  on   your  system   if  you   have  root
      .||    ||             permissions.
       '=    ='

If  you are  not root  make sure  you setup  these           SSSSs
standard parameters for Makefile.pl when the  CPAN            SSSSs
setup program will ask you on the first start with         S a a SS
"> perl -MCPAN -e shell": LIB=<path> PREFIX=<path>         '  -  DS
(for example LIB=/home/ftpd/ PREFIX=/home/ftpd/).           \_= (S
If you  want to  install the module manually  just            _\SS.
use these arguments  when running the  Makefile.pl           (  \ \
script.                                                     / \  \|
                                                           |   >  )\
Additionally    you     have     to     set    the         |_ /  /|/
environment variable $PERL5LIB  to the  path where          |/O_/]
your local perl modules are stored. This will be a        __|/)___\_
subdirectory  of  your  PREFIX:                          /__/|\____/|
                                                         \         ||
For  example:  "> export PERL5LIB=$PERL5LIB:/home/        \________|/
                  ftpd/perl/libdata/perl5/                  |____,_|
                  site_perl/i386-linux"                      %%%%%
                                                              %%%%
The last part depends on your operating system.                %%%%
                                                                %%%
GLIB                                                            %%%
                                                                %%'
Another  requirement  is  glib,  a  usefull   tool              %%
library from  the Gnome  project. If  glib is  not             / O)
installed on  your system  you could  get it  from          ,___/\(
ftp://ftp.gnome.org/pub/GNOME/stable/latest/source
s/ or install the rpm of your distribution or  use
the ports collection on BSD systems.


                            If  you  don't have  root  you have  to  specify a
                            prefix  again  on the  configure  script, like  ">
             __             ./configure   --prefix=/home/ftpd"   Then    "make
            | +|            install"   will   store   the   files   in    your
         ,,,|__|            homedirectory instead of the default location. You
         $$$ , ,            may have  to set  $LD_LIBRARY_PATH to  the path of
        $$C    >            the  glib  shared  objects  too  with  ">   export
       $$$;  _<             LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/ftpd/lib"
   _______/ /_        ___
  |  |__` \~/o\  _,]-]___]-----> CONS BUILD SYSTEM
  | /  \(  )  )\/.-//       Copy the included "cons" script from cons2.2.0/ to
 _( \  )    / \  |          some directory in your $PATH, usually /usr/bin  is
  //| /   ,/   \/           a good place. ("> cp cons2.2.0/cons /usr/bin")  If
    '/   o \                you don't have root use ~/bin and add it to $PATH.
    /     o \               > cp cons2.2.0/cons $HOME/bin
   /______/\_\              > export PATH=$PATH:$HOME/bin
   \   ||   /
    \  ||  /                Type "cons  -h" in  the main  directory, where the
     \ || /                 Construct file  is located,  to see  the available
     / )( \                 options.  Type   "cons .   [<options>]"  to  build
     |/  \|                 OpenFTPD.  A "build/"  directory will  be  created
     :]  [:                 which  you can delete  if  you  want  to   rebuild
     o|  |o                 the    program.  Example: ">  cons  . WARNINGS=yes
    /o|  |o\                NOEXEC=yes"
   `-'  `-'

                                                             _"_ %
IV. INSTALLATION                                             (<  ?
                                                              ` "
An interactive installation script is included and           __||___
you should use  it if you  are not an  experienced          |\___//_\
user who knows already where to put what stuff.             (' | ') \\
Example: > ./install.pl                                   __|\ , /  |/
                                                         /:  /   \  ::
The script will ask you for some options like  the       \| ######o /|
destination path and some basic configuration  and         ######## \)
will copy the files to the selected location.              ########
                                                            \ :  /
                                                             \: /
V. CONFIGURATION                                              --
                                                              %%%
OpenFTPD offers quite a lot configuration  options             %%
which  are  not  always  easy  to   understand for              %
beginners, so you should  read the docs  carefully             /:\
and try to find out how stuff works.                          |/|, b'ger


                            The configuration files  are stored in  the "etc/"
             _____          directory   and   the  most   important   file  is
            ,  ___))        "ftpd.reg"    which     contains    the     global
           /  | 6 6         configuration.   Another   interesting  thing   is
          (___( _e          sections.cfg  if you want to have seperated setups
         ____/ /_           for different parts of your directory tree.
        / \ o\_/ \
       / /\' _  _)\
      /_<  )____/\_\        VI. STARTUP
  ___oo'  ,ooooo,|_/
-//,-(   /      |=/         To start OpenFTPD  run sbin/ftpd which  will start
         |    \  \          the main daemon. Now you can connect to your  ftpd
          \       \         using any ftp  client on the  port you set  in the
           )_______\        install script or in the "etc/ftpd.reg" file.  Use
          /  )   / )        username "root" and an empty password. It's really
         /  /   (  |        recommended that you  setup a password  now. "ftp>
         | /     \ |        site passwd <password>"
 _______ |/_______\|_____ _
         =         =        Now  you  should  have  a  look  at  the available
        /(         )\       commands and checkout  the online help  with "ftp>
       /,/        7 \\_     site  help". For  more information  check out  our
                            homepage http://www.openftpd.org.


VII. FIRST STEPS                                               _____
                                                              /   _)))
The  first  things   should  be  to   create  some           /   / 6 6
directories, setup permissions and add some users.          (   (    \
All there operations can be done with site command          /  ,' __=
(quote site on some clients).                              / _ ) /_  )
                                                          ( /\__~__|(
Make sure that  the user who  is running the  ftpd         /\/__)__) )
got  all  needed  permissions  on  shell  level to        ( /\    (_
access  the  used directories.  Although  the unix         \| \__'/ \
permissions  are  not used  directly  for the  ftp         :o /      \
permissions,   the   process   needs   the  system          /\    _/  )
permissions of course.                                      \/        |
                                                             |        |
Another   important   thing  is   to   assing  ftp           |        |
permissions to the root directory of your site  or           )        |
normal users wont see anything after login.                 /|        )
ftp> site chmod *+cgl /                                    / |________|
                                                           | /      \ |
                                                           |/    ____\!_______
                                                           /          )\
Check out the online help or the website for  more        /(         '-.\_  ..
informations   on  the   available  commands   and       /,/ .. .
options.

              ____________
             |            | VIII. CONTACT
             | OpenFTPD!! |
             |____________| To  contact  the  authors use  the  forum   on the
                 /          website,       write       an       email       to
     _.-----._              primemover@openftpd.org, or visit us in  #openftpd
   _'    '    '_            (efnet)
  '_____________'
      | +_+ |               Please accept  that this  program was  written for
  =--'_D__,'---==.          experienced unix users  (at best with  some coding
 /    > \_/ <     |         skills) and  not for  beginners. So  first try  to
/  >__\o_| o/     |         master  your  operating  system  before  asking us
|      | |_/    , |         stupid questions. Of course we'll try to help with
\,_____/_)  o   | |         real OpenFTPD problems as good as we can.
   |   o '  o   | |
   |   o |  o   |_/|        IX. LICENSE
   '   o |  o   '  |
   |   o |  o   |_/         OpenFTPD was released under the GNU Public License.
   |   o |  o   |))         Read the included COPYING file for more information.
   |     |      |
   |     \      |
   |___o/ \_____|
     |   |   |
-  __)  >|<  (__ --------------------------------------------------------------
  (____,_|_,____)             (c) 2001 Team OpenFTPD / ASCII by Joris Bellenger
                            
