release/src/router/vsftpd/EXAMPLE/VIRTUAL_USERS/README

   1 This example shows how to set up vsftpd / PAM with "virtual users".
   2 A virtual user is a user login which does not exist as a real login on the
   3 system. Virtual users can therefore be more secure than real users, beacuse
   4 a compromised account can only use the FTP server.
   5
   6 Virtual users are often used to serve content that should be accessible to
   7 untrusted users, but not generally accessible to the public.
   8
   9 Step 1) Create the virtual users database.
  10 We are going to use pam_userdb to authenticate the virtual users. This needs
  11 a username / password file in "db" format - a common database format.
  12 To create a "db" format file, first create a plain text files with the
  13 usernames and password on alternating lines.
  14 See example file "logins.txt" - this specifies "tom" with password "foo" and
  15 "fred" with password "bar".
  16 Whilst logged in as root, create the actual database file like this:
  17
  18 db_load -T -t hash -f logins.txt /etc/vsftpd_login.db
  19 (Requires the Berkeley db program installed).
  20 NOTE: Many systems have multiple versions of "db" installed, so you may
  21 need to use e.g. db3_load for correct operation. This is known to affect
  22 some Debian systems. The core issue is that pam_userdb expects its login
  23 database to be a specific db version (often db3, whereas db4 may be installed
  24 on your system).
  25
  26 This will create /etc/vsftpd_login.db. Obviously, you may want to make sure
  27 the permissions are restricted:
  28
  29 chmod 600 /etc/vsftpd_login.db
  30
  31 For more information on maintaing your login database, look around for
  32 documentation on "Berkeley DB", e.g.
  33 http://www.sleepycat.com/docs/utility/index.html
  34
  35
  36 Step 2) Create a PAM file which uses your new database.
  37
  38 See the example file vsftpd.pam. It contains two lines:
  39
  40 auth required /lib/security/pam_userdb.so db=/etc/vsftpd_login
  41 account required /lib/security/pam_userdb.so db=/etc/vsftpd_login
  42
  43 This tells PAM to authenticate users using our new database. Copy this PAM
  44 file to the PAM directory - typically /etc/pam.d/
  45
  46 cp vsftpd.pam /etc/pam.d/ftp
  47
  48 (Note - if you set pam_service_name to e.g. vsftpd instead, you'll need to copy
  49 to /etc/pam.d/vsftpd).
  50
  51
  52 Step 3) Set up the location of the files for the virtual users.
  53
  54 useradd -d /home/ftpsite virtual
  55 ls -ld /home/ftpsite
  56 (which should give):
  57 drwx------    3 virtual  virtual      4096 Jul 30 00:39 /home/ftpsite
  58
  59 We have created a user called "virtual" with a home directory "/home/ftpsite".
  60 Let's add some content to this download area:
  61
  62 cp /etc/hosts /home/ftpsite
  63 chown virtual.virtual /home/ftpsite/hosts
  64
  65
  66 Step 4) Create your vsftpd.conf config file.
  67
  68 See the example in this directory. Let's go through it line by line:
  69
  70 anonymous_enable=NO
  71 local_enable=YES
  72
  73 This disables anonymous FTP for security, and enables non-anonymous FTP (which
  74 is what virtual users use).
  75
  76 write_enable=NO
  77 anon_upload_enable=NO
  78 anon_mkdir_write_enable=NO
  79 anon_other_write_enable=NO
  80
  81 These ensure that for security purposes, no write commands are allowed.
  82
  83 chroot_local_user=YES
  84
  85 This makes sure that the virtual user is restricted to the virtual FTP area
  86 /home/ftpsite we set up above.
  87
  88 guest_enable=YES
  89 guest_username=virtual
  90
  91 The guest_enable is very important - it activates virtual users! And
  92 guest_username says that all virtual users are mapped to the real user
  93 "virtual" that we set up above. This will also determine where on the
  94 filesystem the virtual users end up - the home directory of the user
  95 "virtual", /home/ftpsite.
  96
  97 listen=YES
  98 listen_port=10021
  99
 100 This puts vsftpd in "standalone" mode - i.e. not running from an inetd. This
 101 means you just run the vsftpd executable and it will start up. This also
 102 makes vsftpd listen for FTP requests on the non-standard port of 10021 (FTP
 103 is usually 21).
 104
 105 pasv_min_port=30000
 106 pasv_max_port=30999
 107
 108 These put a port range on passive FTP incoming requests - very useful if
 109 you are configuring a firewall.
 110
 111 Copy the example vsftpd.conf file to /etc:
 112
 113 cp vsftpd.conf /etc/
 114
 115
 116 Step 5) Start up vsftpd.
 117
 118 Go to the directory with the vsftpd binary in it, and:
 119
 120 ./vsftpd
 121
 122 If all is well, the command will sit there. If all is not well, you will
 123 likely see some error message.
 124
 125
 126 Step 6) Test.
 127
 128 Launch another shell session (or background vsftpd with CTRL-Z and then "bg").
 129 Here is an example of an FTP session:
 130
 131 ftp localhost 10021
 132 Connected to localhost (127.0.0.1).
 133 220 ready, dude (vsFTPd 1.1.0: beat me, break me)
 134 Name (localhost:chris): tom
 135 331 Please specify the password.
 136 Password:
 137 230 Login successful. Have fun.
 138 Remote system type is UNIX.
 139 Using binary mode to transfer files.
 140 ftp> pwd
 141 257 "/"
 142 ftp> ls
 143 227 Entering Passive Mode (127,0,0,1,117,135)
 144 150 Here comes the directory listing.
 145 226 Transfer done (but failed to open directory).
 146 ftp> size hosts
 147 213 147
 148 ftp>
 149
 150 Comments:
 151 The password we gave was "foo".
 152 Do not be alarmed by the "failed to open directory". That is because the
 153 directory /home/ftpsite is not world readable (we could change this
 154 behaviour if we wanted using anon_world_readable_only=NO but maybe we want
 155 it this way for security.
 156 We can see that we have access to the "hosts" file we copied into the virtual
 157 FTP area, via the size command.
 158