1Net::FTPServer(3)     User Contributed Perl Documentation    Net::FTPServer(3)
2
3
4

NAME

6       Net::FTPServer - A secure, extensible and configurable Perl FTP server
7

SYNOPSIS

9         ftpd.sh [--help] [-d] [-v] [-p port] [-s] [-S] [-V] [-C conf_file]
10              [-P pidfile] [-o option=value]
11

DESCRIPTION

13       "Net::FTPServer" is a secure, extensible and configurable FTP server
14       written in Perl.
15
16       Current features include:
17
18        * Authenticated FTP access.
19        * Anonymous FTP access.
20        * Complete implementation of current RFCs.
21        * ASCII or binary type file transfers.
22        * Active or passive mode file transfers.
23        * Run standalone or from inetd(8).
24        * Security features: chroot, resource limits, tainting,
25          protection against buffer overflows.
26        * IP-based and/or IP-less virtual hosts.
27        * Complete access control system.
28        * Anonymous read-only FTP personality.
29        * Virtual filesystem allows files to be served
30          from a database.
31        * Directory aliases and CDPATH support.
32        * Extensible command set.
33        * Generate archives on the fly.
34

INSTALLING AND RUNNING THE SERVER

36       A standard "ftpd.conf" file is supplied with the distribution.  Full
37       documentation for all the possible options which you may use in this
38       file is contained in this manual page. See the section CONFIGURATION
39       below.
40
41       After doing "make install", the standard "ftpd.conf" file should have
42       been installed in "/etc/ftpd.conf". You will probably need to edit this
43       file to suit your local configuration.
44
45       Also after doing "make install", several start-up scripts will have
46       been installed in "/usr/sbin/*ftpd.pl". (On Debian in "/usr/bin" or
47       "/usr/local/bin"). Each start-up script starts the server in a
48       different configuration: either as a full FTP server, or as an
49       anonymous-only read-only FTP server, etc.
50
51       The commonly used scripts are:
52
53        * /usr/sbin/ftpd.pl
54        * /usr/sbin/ro-ftpd.pl
55
56       The first script is for the full FTP server.
57
58       These scripts assume that the "perl" interpreter can be found on the
59       current $PATH. In the rare situation when this is not the case, you may
60       need to edit these scripts.
61
62   STANDALONE SERVER
63       If you have a high load site, you will want to run "Net::FTPServer" as
64       a standalone server. To start "Net::FTPServer" as a standalone server,
65       do:
66
67         /usr/sbin/ftpd.pl -S
68
69       You may want to add this to your local start-up files so that the
70       server starts automatically when you boot the machine.
71
72       To stop the server, do:
73
74         killall ftpd.pl
75
76       (Note: "Azazel" points out that the above is a Linux-ism. Solaris
77       administrators may get a nasty shock if they type "killall" as "root"!
78       Just kill the parent "ftpd.pl" process by hand instead).
79
80   RUNNING FROM INETD
81       Add the following line to "/etc/inetd.conf":
82
83         ftp stream tcp nowait root /usr/sbin/tcpd ftpd.pl
84
85       (This assumes that you have the "tcp-wrappers" package installed to
86       provide basic access control through "/etc/hosts.allow" and
87       "/etc/hosts.deny". This access control is in addition to any access
88       control which you may configure through "/etc/ftpd.conf".)
89
90       After editing this file you will need to inform "inetd":
91
92         killall -HUP inetd
93
94   RUNNING FROM XINETD
95       "xinetd" is a modern alternative to "inetd" which is supposedly simpler
96       to configure. In practice, however, it has proven to be quite difficult
97       to configure services under "xinetd" (mainly because "xinetd" gives no
98       diagnostic information when things go wrong). The following
99       configuration has worked for me:
100
101       Create the file "/etc/xinetd.d/net-ftpserver" containing:
102
103        # default: on
104        # description: Net::FTPServer, a secure, \
105        #              extensible, configurable FTP server.
106        #
107        service ftp
108        {
109               socket_type             = stream
110               wait                    = no
111               user                    = root
112               server                  = /usr/sbin/ftpd.pl
113               log_on_success          += DURATION USERID
114               log_on_failure          += USERID
115               disable                 = no
116        }
117
118       Check any other possible FTP server configurations to ensure they are
119       all disabled (ie. "disable = yes" in all other files).
120
121       Restart "xinetd" using:
122
123        /etc/init.d/xinetd restart
124

COMMAND LINE FLAGS

126         --help           Display help and exit
127         -d, -v           Enable debugging
128         -p PORT          Listen on port PORT instead of the default port
129         -s               Run in daemon mode (default: run from inetd)
130         -S               Run in background and in daemon mode
131         -V               Show version information and exit
132         -C CONF          Use CONF as configuration file (default:
133                          /etc/ftpd.conf)
134         -P PIDFILE       Save pid into PIDFILE (daemon mode only)
135         -o option=value  Override config file option with value
136         --test           Test mode (used only in automatic testing scripts)
137

CONFIGURING AND EXTENDING THE SERVER

139       "Net::FTPServer" can be configured and extended in a number of
140       different ways.
141
142       Firstly, almost all common server configuration can be carried out by
143       editing the configuration file "/etc/ftpd.conf".
144
145       Secondly, commands can be loaded into the server at run-time to provide
146       custom extensions to the common FTP command set.  These custom commands
147       are written in Perl.
148
149       Thirdly, one of several different supplied personalities can be chosen.
150       Personalities can be used to make deep changes to the FTP server: for
151       example, there is a supplied personality which allows the FTP server to
152       serve files from a relational database. By subclassing
153       "Net::FTPServer", "Net::FTPServer::DirHandle" and
154       "Net::FTPServer::FileHandle" you may also write your own personalities.
155
156       The next sections talk about each of these possibilities in turn.
157
158   CONFIGURATION
159       A standard "/etc/ftpd.conf" file is supplied with "Net::FTPServer" in
160       the distribution. The possible configuration options are listed in full
161       below.
162
163       Simple configuration options can also be given on the command line
164       using the "-o" option. Command line configuration options override
165       those from the configuration file.
166
167       <Include filename>
168           Use the <Include filename> directive to include the contents of
169           "filename" directly at the current point within the configuration
170           file.
171
172           You cannot use <Include> within a <Host> section, or at least you
173           can but it won't work the way you expect.
174
175       <IncludeWildcard wildcard>
176           Include all files matching "wildcard" at this point in the file.
177           The files are included in alphabetical order.
178
179           You cannot use <IncludeWildcard> within a <Host> section, or at
180           least you can but it won't work the way you expect.
181
182       debug
183           Run with debugging. Equivalent to the command line "-d" option.
184
185           Default: 0
186
187           Example: "debug: 1"
188
189       port
190           The TCP port number on which the FTP server listens when running in
191           daemon mode (see "daemon mode" option below).
192
193           Default: The standard ftp/tcp service port from "/etc/services"
194
195           Example: "port: 8021"
196
197       daemon mode
198           Run as a daemon. If set, the FTP server will open a listening
199           socket on its default port number, accept new connections and fork
200           off a new process to handle each connection. If not set (the
201           default), the FTP server will handle a single connection on
202           stdin/stdout, which is suitable for use from inetd.
203
204           The equivalent command line options are "-s" and "-S".
205
206           Default: 0
207
208           Example: "daemon mode: 1"
209
210       run in background
211           Run in the background. If set, the FTP server will fork into the
212           background before running.
213
214           The equivalent command line option is "-S".
215
216           Default: 0
217
218           Example: "run in background: 1"
219
220       error log
221           If set, then all warning and error messages are appended to this
222           file. If not set, warning and error messages get sent to STDERR and
223           to syslog.
224
225           Having an error log is highly recommended.
226
227           Default: (not set, warnings and errors go to syslog)
228
229           Example: "error log: /var/log/ftpd.errors"
230
231       rotate log files
232           If set, and if the log file names contain a '%' directive, then the
233           server will check if a new log file is needed whenever the system
234           accepts a new connection.  This implements a log rotation feature
235           for long-running servers.
236
237           If not set, then any '%' directive will be evaluated only when the
238           log files gets created.
239
240           Default: (not set, log file name evaluated only once)
241
242           Example: "rotate log files: 1"
243
244       maintainer email
245           Maintainer's email address.
246
247           Default: root@hostname
248
249           Example: "maintainer email: bob@example.com"
250
251       class
252           Assign users into classes. One or more "class" directives can be
253           added to the configuration file to aggregate individual users into
254           larger groups of users called classes.
255
256           By default all anonymous users are in class "anonymous" and every
257           other user is in class "users".
258
259           The configuration file can contain zero or more "class" directives.
260           The format of the class directive is either:
261
262            class: CLASSNAME USERNAME[,USERNAME[,...]]
263
264           or:
265
266            class: CLASSNAME { perl code ... }
267
268           Examples of the first form are:
269
270            class: staff rich
271            class: students ann,mary,pete
272
273           User "rich" will be placed into class "staff", and users "ann",
274           "mary" and "pete" will be placed into class "students".
275
276           Examples of the second form are:
277
278            class: family { /jones$/ }
279            class: friends { $_ ne "jeff" }
280
281           Any username ending in "jones" (eg. "rjones", "timjones") will be
282           in class "family". Any other user except "jeff" will be placed in
283           class "friends". Note that the Perl code must be surrounded by
284           "{...}" and must return a boolean true or false value. The username
285           is available as $_. The Perl code is arbitrary: it might, for
286           example, use an external file or database lookup in order to work
287           out if a user belongs to a class.
288
289           "class" directives are evaluated in the order in which they appear
290           in the configuration file until one matches the username.
291
292           Default: Anonymous users are assigned to class "anonymous" and
293           everyone else is assigned to class "users".
294
295       timeout
296           Timeout on control connection. If a command has not been received
297           after this many seconds, the server drops the connection. You may
298           set this to zero to disable timeouts completely (although this is
299           not recommended).
300
301           Default: 900 (seconds)
302
303           Example: "timeout: 600"
304
305       limit memory
306       limit nr processes
307       limit nr files
308           Resource limits. These limits are applied to each child process and
309           are important in avoiding denial of service (DoS) attacks against
310           the FTP server.
311
312            Resource         Default   Unit
313            limit memory       65536   KBytes  Amount of memory per child
314            limit nr processes    10   (none)  Number of processes
315            limit nr files        20   (none)  Number of open files
316
317           To instruct the server not to limit a particular resource, set the
318           limit to "-1".
319
320           Example:
321
322            limit memory:      131072
323            limit nr processes:    20
324            limit nr files:        40
325
326            limit nr processes:    -1
327
328       max clients
329           Limit on the number of clients who can simultaneously connect.  If
330           this limit is ever reached, new clients will immediately be closed.
331           It will not even ask the client to login.  This feature works in
332           daemon mode only.
333
334           Default: 255
335
336           Example: "max clients: 600"
337
338       max clients message
339           Message to display when ``max clients'' has been reached.
340
341           You may use the following % escape sequences within the message for
342           internal variables:
343
344            %x  ``max clients'' setting that has been reached
345            %E  maintainer email address (from ``maintainer email''
346                setting above)
347            %G  time in GMT
348            %R  remote hostname or IP address if ``resolve addresses''
349                is not set
350            %L  local hostname
351            %T  local time
352            %%  just an ordinary ``%''
353
354           Default: Maximum connections reached
355
356           Example: "max clients message: Only %x simultaneous connections
357           allowed.  Please try again later."
358
359       resolve addresses
360           Resolve addresses. If set, attempt to do a reverse lookup on client
361           addresses for logging purposes. If you set this then some clients
362           may experience long delays when they try to connect. Not
363           recommended on high load servers.
364
365           Default: 0
366
367           Example: "resolve addresses: 1"
368
369       require resolved addresses
370           Require resolved addresses. If set, client addresses must validly
371           resolve otherwise clients will not be able to connect. If you set
372           this then some clients will not be able to connect, even though it
373           is probably the fault of their ISP.
374
375           Default: 0
376
377           Example: "require resolved addresses: 1"
378
379       change process name
380           Change process name. If set (the default) then the FTP server will
381           change its process name to reflect the IP address or hostname of
382           the client. If not set then the FTP server will not try to change
383           its process name.
384
385           Default: 1
386
387           Example: "change process name: 0"
388
389       greeting type
390           Greeting type. The greeting is printed before the user has logged
391           in.  Possible greeting types are:
392
393               full     Full greeting, including hostname and version number.
394               brief    Hostname only.
395               terse    Nothing
396               text     Display greeting from ``greeting text'' option.
397
398           The SITE VERSION command can also reveal the version number. You
399           may need to turn this off by setting "allow site version command:
400           0" below.
401
402           Default: full
403
404           Example: "greeting type: text"
405
406       greeting text
407           Greeting text. If the "greeting type" is set to "text" then this
408           contains the text to display.
409
410           Default: none
411
412           Example: "greeting text: Hello. I'll be your server today."
413
414       welcome type
415           Welcome type. The welcome is printed after a user has logged in.
416           Possible welcome types are:
417
418               normal   Normal welcome message: ``Welcome <<username>>.''
419               text     Take the welcome message from ``welcome text'' option.
420               file     Take the welcome message from ``welcome file'' file.
421
422           Default: normal
423
424           Example: "welcome type: text"
425
426       welcome text
427           If "welcome type" is set to "text", then this contains the text to
428           be printed after a user has logged in.
429
430           You may use the following % escape sequences within the welcome
431           text to substitute for internal variables:
432
433            %E  maintainer's email address (from ``maintainer email''
434                setting above)
435            %G  time in GMT
436            %R  remote hostname or IP address if ``resolve addresses''
437                is not set
438            %L  local hostname
439            %m  user's home directory (see ``home directory'' below)
440            %T  local time
441            %U  username given when logging in
442            %u  currently a synonym for %U, but in future will be
443                determined from RFC931 authentication, like wu-ftpd
444            %%  just an ordinary ``%''
445
446           Default: none
447
448           Example: "welcome text: Welcome to this FTP server."
449
450       welcome file
451           If "welcome type" is set to "file", then this contains the file to
452           be printed after a user has logged in.
453
454           You may use any of the % escape sequences defined in "welcome text"
455           above.
456
457           Default: none
458
459           Example: "welcome file: /etc/motd"
460
461       home directory
462           Home directory. This is the home directory where we put the user
463           once they have logged in. This only applies to non-anonymous
464           logins. Anonymous logins are always placed in "/", which is at the
465           root of their chrooted environment.
466
467           You may use an absolute path here, or else one of the following
468           special forms:
469
470            %m   Use home directory from password file or from NSS.
471            %U   Username.
472            %%   A single % character.
473
474           For example, to force a user to start in "~/anon-ftp" when they log
475           in, set this to "%m/anon-ftp".
476
477           Note that setting the home directory does not perform a chroot.
478           Use the "root directory" setting below to jail users into a
479           particular directory.
480
481           Home directories are relative to the current root directory.
482
483           In the anonymous read-only (ro-ftpd) personality, set home
484           directory to "/" or else you will get a warning whenever a user
485           logs in.
486
487           Default: %m
488
489           Examples:
490
491            home directory: %m/anon-ftp
492            home directory: /
493
494       root directory
495           Root directory. Immediately after logging in, perform a chroot into
496           the named directory. This only applies to non-anonymous logins, and
497           furthermore it only applies if you have a non-database VFS
498           installed. Database VFSes typically cannot perform chroot (or, to
499           be more accurate, they have a different concept of chroot -
500           typically assigning each user their own completely separate
501           namespace).
502
503           You may use %m and %U as above.
504
505           For example, to jail a user under "~/anon-ftp" after login, do:
506
507             home directory: /
508             root directory: %m/anon-ftp
509
510           Notice that the home directory is relative to the current root
511           directory.
512
513           Default: (none)
514
515           Example: "root directory: %m/anon-ftp"
516
517       time zone
518           Time zone to be used for MDTM and LIST stat information.
519
520           Default: GMT
521
522           Examples:
523
524            time zone: Etc/GMT+3
525            time zone: Europe/London
526            time zone: US/Mountain
527
528       local address
529           Local addresses. If you wish the FTP server (in daemon mode) to
530           only bind to a particular local interface, then give its address
531           here.
532
533           Default: none
534
535           Example: "local address: 127.0.0.1"
536
537       allow anonymous
538           Allow anonymous access. If set, then allow anonymous access through
539           the "ftp" and "anonymous" accounts.
540
541           Default: 0
542
543           Example: "allow anonymous: 1"
544
545       anonymous password check
546       anonymous password enforce
547           Validate email addresses. Normally when logging in anonymously, you
548           are asked to enter your email address as a password. These options
549           can be used to check and enforce email addresses in this field (to
550           some extent, at least -- you obviously can't force someone to enter
551           a true email address).
552
553           The "anonymous password check" option may be set to "rfc822", "no
554           browser", "trivial" or "none". If set to "rfc822" then the user
555           must enter a valid RFC 822 email address as password. If set to "no
556           browser" then a valid RFC 822 email address must be entered, and
557           various common browser email addresses like "mozilla@" and
558           "IEverUser@" are refused. If set to "trivial" then we just check
559           that the address contains an @ char. If set to "none", then we do
560           no checking. The default is "none".
561
562           If the "anonymous password enforce" option is set and the password
563           fails the check above, then the user will not be allowed to log in.
564           The default is 0 (unset).
565
566           These options only have effect when "allow anonymous" is set.
567
568           Example:
569
570            anonymous password check: rfc822
571            anonymous password enforce: 1
572
573       allow proxy ftp
574           Allow proxy FTP. If this is set, then the FTP server can be told to
575           actively connect to addresses and ports on any machine in the
576           world.  This is not such a great idea, but required if you follow
577           the RFC very closely. If not set (the default), the FTP server will
578           only connect back to the client machine.
579
580           Default: 0
581
582           Example: "allow proxy ftp: 1"
583
584       allow connect low port
585           Allow the FTP server to connect back to ports < 1024. This is
586           rarely useful and could pose a serious security hole in some
587           circumstances.
588
589           Default: 0
590
591           Example: "allow connect low port: 1"
592
593       passive port range
594           What range of local ports will the FTP server listen on in passive
595           mode? Choose a range here like "1024-5999,49152-65535". The special
596           value 0 means that the FTP server will use a kernel-assigned
597           ephemeral port.
598
599           Default: 49152-65535
600
601           Example: "passive port range: 0"
602
603       ftp data port
604           Which source port to use for active (non-passive) mode when
605           connecting to the client for PORT mode transfers.  The special
606           value 0 means that the FTP server will use a kernel-assigned
607           ephemeral port.  To strictly follow RFC, this should be set to
608           "ftp-data(20)".  This may be required for certain brain-damaged
609           firewall configurations.  However, for security reasons, the
610           default setting is intentionally set to 0 to utilize a kernel-
611           assigned ephemeral port.  Use this directive at your own risk!
612
613           SECURITY PRECAUTIONS:
614
615           1) Unfortunately, to use a port < 1024 requires super-user
616           privileges.  Thus, low ports will not work unless the FTP server is
617           invoked as super-user.  This also implies that all processes
618           handling the client connections must also remain super-user
619           throughout the entire session.  It is highly discouraged to use a
620           low port.
621
622            http://cr.yp.to/ftp/security.html
623            (See "Connection laundering" section)
624
625           2) There sometimes exists a danger of needing to connect to the
626           same remote host:port.  Using the same IP/port on both sides will
627           cause connect() to fail if the old socket is still being broken
628           down.  This condition will not occur if using an ephemeral port.
629
630            http://groups.google.com/groups?selm=fa.epucqgv.1l2kl0e@ifi.uio.no
631            (See "unable to create socket" comment)
632
633           3) Many hackers use source port 20 to blindly circumvent certain
634           naive firewalls.  Using an ephemeral port (the default) may help
635           discourage such dangerous naivety.
636
637            man nmap
638            (See the -g option)
639
640           Default: 0
641
642           Example: "ftp data port: ftp-data"
643
644       max login attempts
645           Maximum number of login attempts before we drop the connection and
646           issue a warning in the logs. Wu-ftpd defaults this to 5.
647
648           Default: 3
649
650           Example: "max login attempts: 5"
651
652       pam authentication
653           Use PAM for authentication. Required on systems such as Red Hat
654           Linux and Solaris which use PAM for authentication rather than the
655           normal "/etc/passwd" mechanisms. You will need to have the
656           "Authen::PAM" Perl module installed for this to work.
657
658           Default: 0
659
660           Example: "pam authentication: 1"
661
662       pam application name
663           If PAM authentication is enabled, then this is the PAM application
664           name. I have used "ftp" as the default which is the same name that
665           wu-ftpd chooses. FreeBSD users will want to use "ftpd" here.
666
667           Default: ftp
668
669           Example: "pam application name: ftpd"
670
671       password file
672           Only in the "Full" personality, this allows you to specify a
673           password file which is used for authentication. If you enable this
674           option, then normal PAM or "/etc/passwd" is bypassed and this
675           password file is used instead.
676
677           Each line in the password file has the following format:
678
679            username:crypted_password:unix_user[:root_directory]
680
681           Comments and blank lines are ignored.
682
683           For example, a line with:
684
685            guest:ab01FAX.bQRSU:rich:/home/rich/guest-uploads
686
687           would allow someone to log in as "guest" with password 123456.
688           After logging in, the FTP server will assume the identity of the
689           real Unix user "rich", and will chroot itself into the
690           "/home/rich/guest-uploads" directory.
691
692           (Note that because ordinary PAM/"passwd" is bypassed, it would no
693           longer be possible for a user to log in directly with the username
694           "rich").
695
696           Crypted passwords can be generated using the following command:
697
698            perl -e 'print crypt ("123456", "ab"), "\n"'
699
700           Replace 123456 with the actual password, and replace "ab" with two
701           random letters from the set "[a-zA-Z0-9./]". (The two random
702           letters are the so-called salt and are used to make dictionary
703           attacks against the password file more difficult - see crypt(3)).
704
705           The user's home directory comes from the real Unix password file
706           (or nsswitch-configured source) for the real Unix user.  You cannot
707           use password files to override this, and so if you are using the
708           optional "root_directory" parameter, it would make sense to add
709           "home directory: /" into your configuration file.
710
711           Anonymous logins are not affected by the "password file" option.
712           Use the "allow anonymous" flag to control whether anonymous logins
713           are permitted in the "Full" back-end.
714
715           Password files are not the height of security, but they are
716           included because they can sometimes be useful. In particular if the
717           password file can be read by untrusted users then it is likely that
718           those same users can run the crack program and eventually find out
719           your passwords. Some small additional security is offered by having
720           the password file readable only by root (mode 0600). In future we
721           may offer MD5 or salted SHA-1 hashed passwords to make this harder.
722
723           A curious artifact of the implementation allows you to list the
724           same user with multiple different passwords. Any of the passwords
725           is then valid for logins (and you could even have the user map to
726           different real Unix users in different chrooted directories!)
727
728           Default: (none)
729
730           Example: "password file: /etc/ftpd.passwd"
731
732       pidfile
733           Location of the file to store the process ID (PID).  Applies only
734           to the deamonized process, not the child processes.
735
736           Default: (no pidfile created)
737
738           Example: "pidfile: /var/run/ftpd.pid"
739
740       client logging
741           Location to store all client commands sent to the server.  The
742           format is the date, the pid, and the command.  Following the pid is
743           a "-" if not authenticated the username if the connection is
744           authenticated.  Example of before and after authentication:
745
746            [Wed Feb 21 18:41:32 2001][23818:-]USER rob
747            [Wed Feb 21 18:41:33 2001][23818:-]PASS 123456
748            [Wed Feb 21 18:41:33 2001][23818:*]SYST
749
750           Default: (no logging)
751
752           Examples:
753
754            client logging: /var/log/ftpd.log
755            client logging: /tmp/ftpd_log.$hostname
756
757       xfer logging
758           Location of transfer log.  The format was taken from wu-ftpd and
759           ProFTPD xferlog. (See also "man xferlog")
760
761           Default: (no logging)
762
763           Examples:
764
765            xfer logging: /var/log/xferlog
766            xfer logging: /tmp/xferlog.$hostname
767
768       hide passwords in client log
769           If set to 1, then password ("PASS") commands will not be logged in
770           the client log. This option has no effect unless client logging is
771           enabled.
772
773           Default: 0 (PASS lines will be shown)
774
775           Example: "hide passwords in client log: 1"
776
777       enable syslog
778           Enable syslogging. If set, then Net::FTPServer will send much
779           information to syslog. On many systems, this information will be
780           available in /var/log/messages or /var/adm/messages. If clear,
781           syslogging is disabled.
782
783           Default: 1
784
785           Example: "enable syslog: 0"
786
787       ident timeout
788           Timeout for ident authentication lookups.  A timeout (in seconds)
789           must be specified in order to enable ident lookups.  There is no
790           way to specify an infinite timeout.  Use 0 to disable this feature.
791
792           Default: 0
793
794           Example: "ident timeout: 10"
795
796       access control rule
797       user access control rule
798       retrieve rule
799       store rule
800       delete rule
801       list rule
802       mkdir rule
803       rename rule
804       chdir rule
805           Access control rules.
806
807           Access control rules are all specified as short snippets of Perl
808           script. This allows the maximum configurability -- you can express
809           just about any rules you want -- but at the price of learning a
810           little Perl.
811
812           You can use the following variables from the Perl:
813
814            $hostname      Resolved hostname of the client [1]
815            $ip            IP address of the client
816            $user          User name [2]
817            $class         Class of user [2]
818            $user_is_anonymous  True if the user is an anonymous user [2]
819            $pathname      Full pathname of the file being affected [2]
820            $filename      Filename of the file being affected [2,3]
821            $dirname       Directory name containing file being affected [2]
822            $type          'A' for ASCII, 'B' for binary, 'L8' for local 8-bit
823            $form          Always 'N'
824            $mode          Always 'S'
825            $stru          Always 'F'
826
827           Notes:
828
829           [1] May be undefined, particularly if "resolve addresses" is not
830           set.
831
832           [2] Not available in "access control rule" since the user has not
833           logged in at this point.
834
835           [3] Not available for "list directory rule".
836
837           Access control rule. The FTP server will not accept any connections
838           from a site unless this rule succeeds. Note that only $hostname and
839           $ip are available to this rule, and unless "resolve addresses" and
840           "require resolved addresses" are both set $hostname may be
841           undefined.
842
843           Default: 1
844
845           Examples:
846
847            (a) Deny connections from *.badguys.com:
848
849                access control rule: defined ($hostname) && \
850                                     $hostname !~ /\.badguys\.com$/
851
852            (b) Only allow connections from local network 10.0.0.0/24:
853
854                access control rule: $ip =~ /^10\./
855
856           User access control rule. After the user logs in successfully, this
857           rule is then called to determine if the user may be permitted
858           access.
859
860           Default: 1
861
862           Examples:
863
864            (a) Only allow ``rich'' to log in from 10.x.x.x network:
865
866                user access control rule: $user ne "rich" || \
867                                          $ip =~ /^10\./
868
869            (b) Only allow anonymous users to log in if they come from
870                hosts with resolving hostnames (``resolve addresses'' must
871                also be set):
872
873                user access control rule: !$user_is_anonymous || \
874                                          defined ($hostname)
875
876            (c) Do not allow user ``jeff'' to log in at all:
877
878                user access control rule: $user ne "jeff"
879
880           Retrieve rule. This rule controls who may retrieve (download)
881           files.
882
883           Default: 1
884
885           Examples:
886
887            (a) Do not allow anyone to retrieve ``/etc/*'' or any file anywhere
888                called ``.htaccess'':
889
890                retrieve rule: $dirname !~ m(^/etc/) && $filename ne ".htaccess"
891
892            (b) Only allow anonymous users to retrieve files from under the
893                ``/pub'' directory.
894
895                retrieve rule: !$user_is_anonymous || $dirname =~ m(^/pub/)
896
897           Store rule. This rule controls who may store (upload) files.
898
899           In the anonymous read-only (ro-ftpd) personality, it is not
900           possible to upload files anyway, so setting this rule has no
901           effect.
902
903           Default: 1
904
905           Examples:
906
907            (a) Only allow users to upload files to the ``/incoming''
908                directory.
909
910                store rule: $dirname =~ m(^/incoming/)
911
912            (b) Anonymous users can only upload files to ``/incoming''
913                directory.
914
915                store rule: !$user_is_anonymous || $dirname =~ m(^/incoming/)
916
917            (c) Disable file upload.
918
919                store rule: 0
920
921           Delete rule. This rule controls who may delete files or rmdir
922           directories.
923
924           In the anonymous read-only (ro-ftpd) personality, it is not
925           possible to delete files anyway, so setting this rule has no
926           effect.
927
928           Default: 1
929
930           Example: "delete rule: 0"
931
932           List rule. This rule controls who may list out the contents of a
933           directory.
934
935           Default: 1
936
937           Example: "list rule: $dirname =~ m(^/pub/)"
938
939           Mkdir rule. This rule controls who may create a subdirectory.
940
941           In the anonymous read-only (ro-ftpd) personality, it is not
942           possible to create directories anyway, so setting this rule has no
943           effect.
944
945           Default: 1
946
947           Example: "mkdir rule: 0"
948
949           Rename rule. This rule controls which files or directories can be
950           renamed.
951
952           Default: 1
953
954           Example: "rename rule: $pathname !~ m(/.htaccess$)"
955
956           Chdir rule. This rule controls which directories are acceptable to
957           a CWD or CDUP.
958
959           Example: "chdir rule: $pathname !~ m/private/"
960
961       chdir message file
962           Change directory message file. If set, then the first time (per
963           session) that a user goes into a directory which contains a file
964           matching this name, that file will be displayed.
965
966           The file may contain any of the following % escape sequences:
967
968            %C  current working directory
969            %E  maintainer's email address (from ``maintainer email''
970                setting above)
971            %G  time in GMT
972            %R  remote hostname or IP address if ``resolve addresses''
973                is not set
974            %L  local hostname
975            %m  user's home directory (see ``home directory'' below)
976            %T  local time
977            %U  username given when logging in
978            %u  currently a synonym for %U, but in future will be
979                determined from RFC931 authentication, like wu-ftpd
980            %%  just an ordinary ``%''
981
982           Default: (none)
983
984           Example: "chdir message file: .message"
985
986       allow rename to overwrite
987           Allow the rename (RNFR/RNTO) command to overwrite files. If unset,
988           then we try to test whether the rename command would overwrite a
989           file and disallow it. However there are some race conditions with
990           this test.
991
992           Default: 1
993
994           Example: "allow rename to overwrite: 0"
995
996       allow store to overwrite
997           Allow the store commands (STOR/STOU/APPE) to overwrite files. If
998           unset, then we try to test whether the store command would
999           overwrite a file and disallow it. However there are some race
1000           conditions with this test.
1001
1002           Default: 1
1003
1004           Example: "allow store to overwrite: 0"
1005
1006       alias
1007           Define an alias "name" for directory "dir". For example, the
1008           command "alias: mirror /pub/mirror" would allow the user to access
1009           the "/pub/mirror" directory directly just by typing "cd mirror".
1010
1011           Aliases only apply to the cd (CWD) command. The "cd foo" command
1012           checks for directories in the following order:
1013
1014            foo in the current directory
1015            an alias called foo
1016            foo in each directory in the cdpath (see ``cdpath'' command below)
1017
1018           You may list an many aliases as you want.
1019
1020           Alias names cannot contain slashes (/).
1021
1022           Although alias dirs may start without a slash (/), this is unwise
1023           and it's better that they always start with a slash (/) char.
1024
1025           General format: "alias: name dir"
1026
1027       cdpath
1028           Define a search path which is used when changing directories. For
1029           example, the command "cdpath: /pub/mirror /pub/sites" would allow
1030           the user to access the "/pub/mirror/ftp.cpan.org" directory
1031           directly by just typing "cd ftp.cpan.org".
1032
1033           The "cd foo" command checks for directories in the following order:
1034
1035            foo in the current directory
1036            an alias called foo (see ``alias'' command above)
1037            foo in each directory in the cdpath
1038
1039           General format: "cdpath: dir1 [dir2 [dir3 ...]]"
1040
1041       allow site version command
1042           SITE VERSION command. If set, then the SITE VERSION command reveals
1043           the current Net::FTPServer version string. If unset, then the
1044           command is disabled.
1045
1046           Default: 1
1047
1048           Example: "allow site version command: 0"
1049
1050       allow site exec command
1051           SITE EXEC command. If set, then the SITE EXEC command allows
1052           arbitrary commands to be executed on the server as the current
1053           user. If unset, then this command is disabled. The default is
1054           disabled for obvious security reasons.
1055
1056           If you do allow SITE EXEC, you may need to increase the per process
1057           memory, processes and files limits above.
1058
1059           Default: 0
1060
1061           Example: "allow site exec command: 1"
1062
1063       enable archive mode
1064           Archive mode. If set (the default), then archive mode is enabled,
1065           allowing users to request, say, "file.gz" and get a version of
1066           "file" which is gzip-compressed on the fly. If zero, then this
1067           feature is disabled. See the section ARCHIVE MODE elsewhere in this
1068           manual for details.
1069
1070           Since archive mode is implemented using external commands, you need
1071           to ensure that programs such as "gzip", "compress", "bzip2",
1072           "uuencode", etc. are available on the $PATH (even in the chrooted
1073           environment), and you also need to substantially increase the
1074           normal per-process memory, processes and files limits.
1075
1076           Default: 1
1077
1078           Example: "enable archive mode: 0"
1079
1080       archive zip temporaries
1081           Temporary directory for generating ZIP files in archive mode.  In
1082           archive mode, when generating ZIP files, the FTP server is capable
1083           of either creating a temporary file on local disk containing the
1084           ZIP contents, or can generate the file completely in memory. The
1085           former method saves memory. The latter method (only practical on
1086           small ZIP files) allows the server to work more securely and in
1087           certain read-only chrooted environments.
1088
1089           (Unfortunately the ZIP file format itself prevents ZIP files from
1090           being easily created on the fly).
1091
1092           If not specified in the configuration file, this option defaults to
1093           using "/tmp". If there are local users on the FTP server box, then
1094           this can lead to various "tmp" races, so for maximum security you
1095           will probably want to change this.
1096
1097           If specified, and set to a string, then the string is the name of a
1098           directory which is used for storing temporary zip files. This
1099           directory must be writable, and must exist inside the chrooted
1100           environment (if chroot is being used).
1101
1102           If specified, but set to "0" or an empty string, then the server
1103           will always generate the ZIP file in memory.
1104
1105           In any case, if the directory is found at runtime to be unwritable,
1106           then the server falls back to creating ZIP files in memory.
1107
1108           Default: "/tmp"
1109
1110           Example: "archive zip temporaries: "
1111
1112           Example: "archive zip temporaries: /var/ziptmp"
1113
1114       site command
1115           Custom SITE commands. Use this command to define custom SITE
1116           commands. Please read the section LOADING CUSTOMIZED SITE COMMANDS
1117           in this manual page for more detailed information.
1118
1119           The "site command" command has the form:
1120
1121           "site command: cmdname file"
1122
1123           cmdname is the name of the command (eg. for SITE README you would
1124           set cmdname == "readme"). file is a file containing the code of the
1125           site command in the form of an anonymous Perl subroutine. The file
1126           should have the form:
1127
1128            sub {
1129              my $self = shift;            # The FTPServer object.
1130              my $cmd = shift;             # Contains the command itself.
1131              my $rest = shift;            # Contains any parameters passed by the user.
1132
1133                 :     :
1134                 :     :
1135
1136              $self->reply (RESPONSE_CODE, RESPONSE_TEXT);
1137            }
1138
1139           You may define as many site commands as you want. You may also
1140           override site commands from the current personality here.
1141
1142           Example:
1143
1144            site command: quota /usr/local/lib/ftp/quota.pl
1145
1146           and the file "/usr/local/lib/ftp/quota.pl" contains:
1147
1148            sub {
1149              my $self = shift;            # The FTPServer object.
1150              my $cmd = shift;             # Contains "QUOTA".
1151              my $rest = shift;            # Contains parameters passed by user.
1152
1153              # ... Some code to compute the user's quota ...
1154
1155              $self->reply (200, "Your quota is $quota MB.");
1156            }
1157
1158           The client types "SITE QUOTA" and the server responds with:
1159
1160            "200 Your quota is 12.5 MB.".
1161
1162       <Host hostname> ... </Host>
1163           <Host hostname> ... </Host> encloses commands which are applicable
1164           only to a particular host. "hostname" may be either a fully-
1165           qualified domain name (for IP-less virtual hosts) or an IP address
1166           (for IP-based virtual hosts). You should read the section VIRTUAL
1167           HOSTS in this manual page for more information on the different
1168           types of virtual hosts and how to set it up in more detail.
1169
1170           Note also that unless you have set "enable virtual hosts: 1", all
1171           <Host> sections will be ignored.
1172
1173       enable virtual hosts
1174           Unless this option is uncommented, virtual hosting is disabled and
1175           the <Host> sections in the configuration file have no effect.
1176
1177           Default: 0
1178
1179           Example: "enable virtual hosts: 1"
1180
1181       virtual host multiplex
1182           IP-less virtual hosts. If you want to enable IP-less virtual hosts,
1183           then you must set up your DNS so that all hosts map to a single IP
1184           address, and place that IP address here. This is roughly equivalent
1185           to the Apache "NameVirtualHost" option.
1186
1187           IP-less virtual hosting is an experimental feature which requires
1188           changes to clients.
1189
1190           Default: (none)
1191
1192           Example: "virtual host multiplex: 1.2.3.4"
1193
1194           Example <Host> section. Allow the dangerous SITE EXEC command on
1195           local connections. (Note that this is still dangerous).
1196
1197            <Host localhost.localdomain>
1198              ip: 127.0.0.1
1199              allow site exec command: 1
1200            </Host>
1201
1202           Example <Host> section. This shows you how to do IP-based virtual
1203           hosts. I assume that you have set up your DNS so that
1204           "ftp.bob.example.com" maps to IP 1.2.3.4 and "ftp.jane.example.com"
1205           maps to IP 1.2.3.5, and you have set up suitable IP aliasing in the
1206           kernel.
1207
1208           You do not need the "ip:" command if you have configured reverse
1209           DNS correctly AND you trust your local DNS servers.
1210
1211            <Host ftp.bob.example.com>
1212              ip: 1.2.3.4
1213              root directory: /home/bob
1214              home directory: /
1215              user access control rule: $user eq "bob"
1216              maintainer email: bob@bob.example.com
1217            </Host>
1218
1219            <Host ftp.jane.example.com>
1220              ip: 1.2.3.5
1221              root directory: /home/jane
1222              home directory: /
1223              allow anonymous: 1
1224              user access control rule: $user_is_anonymous
1225              maintainer email: jane@jane.example.com
1226            </Host>
1227
1228           These rules set up two virtual hosts called "ftp.bob.example.com"
1229           and "ftp.jane.example.com". The former is located under bob's home
1230           directory and only he is allowed to log in. The latter is located
1231           under jane's home directory and only allows anonymous access.
1232
1233           Example <Host> section. This shows you how to do IP-less virtual
1234           hosts. Note that IP-less virtual hosts are a highly experimental
1235           feature, and require the client to support the HOST command.
1236
1237           You need to set up your DNS so that both "ftp.bob.example.com" and
1238           "ftp.jane.example.com" point to your own IP address.
1239
1240            virtual host multiplex: 1.2.3.4
1241
1242            <Host ftp.bob.example.com>
1243              root directory: /home/bob
1244              home directory: /
1245              user access control rule: $user eq "bob"
1246            </Host>
1247
1248            <Host ftp.jane.example.com>
1249              root directory: /home/jane
1250              home directory: /
1251              allow anonymous: 1
1252              user access control rule: $user_is_anonymous
1253            </Host>
1254
1255       log socket type
1256           Socket type for contacting syslog. This is the argument to the
1257           "Sys::Syslog::setlogsock" function.
1258
1259           Default: unix
1260
1261           Example: "log socket type: inet"
1262
1263       listen queue
1264           Length of the listen queue when running in daemon mode.
1265
1266           Default: 10
1267
1268           Example: "listen queue: 20"
1269
1270       tcp window
1271           Set TCP window. See RFC 2415 Simulation Studies of Increased
1272           Initial TCP Window Size.  This setting only affects the data
1273           socket. It's not likely that you will need to or should change this
1274           setting from the system-specific default.
1275
1276           Default: (system-specific TCP window size)
1277
1278           Example: "tcp window: 4380"
1279
1280       tcp keepalive
1281           Set TCP keepalive.
1282
1283           Default: (system-specific keepalive setting)
1284
1285           Example: "tcp keepalive: 1"
1286
1287       command filter
1288           Command filter. If set, then all commands are checked against this
1289           regular expression before being executed. If a command doesn't
1290           match the filter, then the command connection is immediately
1291           dropped. This is equivalent to the "AllowFilter" command in
1292           ProFTPD. Remember to include "^...$" around the filter.
1293
1294           Default: (no filter)
1295
1296           Example: "command filter: ^[A-Za-z0-9 /]+$"
1297
1298       restrict command
1299           Advanced command filtering. The "restrict command" directive takes
1300           the form:
1301
1302            restrict command: "COMMAND" perl code ...
1303
1304           If the user tries to execute "COMMAND", then the "perl code" is
1305           evaluated first. If it evaluates to true, then the command is
1306           allowed to proceed. Otherwise the server reports an error back to
1307           the user and does not execute the command.
1308
1309           Note that the "COMMAND" is the FTP protocol command, which is not
1310           necessarily the same as the command which users will type in on
1311           their FTP clients. Please read RFC 959 to see some of the more
1312           common FTP protocol commands.
1313
1314           The Perl code has the same variables available to it as for access
1315           control rules (eg. $user, $class, $ip, etc.). The code must not
1316           alter the global $_ variable (which contains the complete command).
1317
1318           Default: all commands are allowed by default
1319
1320           Examples:
1321
1322           Only allow users in the class "nukers" to delete files and
1323           directories:
1324
1325            restrict command: "DELE" $class eq "nukers"
1326            restrict command: "RMD" $class eq "nukers"
1327
1328           Only allow staff to use the "SITE WHO" command:
1329
1330            restrict command: "SITE WHO" $class eq "staff"
1331
1332           Only allow "rich" to run the "SITE EXEC" command:
1333
1334            allow site exec command: 1
1335            restrict command: "SITE EXEC" $user eq "rich"
1336
1337       command wait
1338           Go slow. If set, then the server will sleep for this many seconds
1339           before beginning to process each command. This command would be a
1340           lot more useful if you could apply it only to particular classes of
1341           connection.
1342
1343           Default: (no wait)
1344
1345           Example: "command wait: 5"
1346
1347       no authentication commands
1348           The list of commands which a client may issue before they have
1349           authenticated themselves is very limited. Obviously "USER" and
1350           "PASS" are allowed (otherwise a user would never be able to log
1351           in!), also "QUIT", "LANG", "HOST" and "FEAT". "HELP" is also
1352           permitted (although dubious). Any other commands not on this list
1353           will result in a 530 Not logged in. error.
1354
1355           This list ought to contain at least "USER", "PASS" and "QUIT"
1356           otherwise the server won't be very functional.
1357
1358           Some commands cannot be added here -- eg. adding "CWD" or "RETR" to
1359           this list is likely to make the FTP server crash, or else enable
1360           users to read files only available to root. Hence use this with
1361           great care.
1362
1363           Default: USER PASS QUIT LANG HOST FEAT HELP
1364
1365           Example: "no authentication commands: USER PASS QUIT"
1366
1367       <Perl> ... </Perl>
1368           Use the <Perl> directive to write Perl code directly into your
1369           configuration file. Here is a simple example:
1370
1371            <Perl>
1372            use Sys::Hostname;
1373            $config{'maintainer email'} = "root\@" . hostname ();
1374            $config{port} = 8000 + 21;
1375            $config{debug} = $ENV{FTP_DEBUG} ? 1 : 0;
1376            </Perl>
1377
1378           As shown in the example, to set a configuration option called
1379           "foo", you simply assign to the variable $config{foo}.
1380
1381           All normal Perl functionality is available to you, including use of
1382           "require" if you need to run an external Perl script.
1383
1384           The <Perl> and </Perl> directives must each appear on a single line
1385           on their own.
1386
1387           To assign multiple configuration options with the same name, use an
1388           array ref:
1389
1390            <Perl>
1391            my @aliases = ( "foo /pub/foo",
1392                            "bar /pub/bar",
1393                            "baz /pub/baz" );
1394            $config{alias} = \@aliases;
1395            </Perl>
1396
1397           You cannot use a <Perl> section within a <Host> section. Instead,
1398           you must simulate it by assigning to the %host_config variable like
1399           this:
1400
1401            <Perl>
1402            $host_config{'localhost.localdomain'}{ip} = "127.0.0.1";
1403            $host_config{'localhost.localdomain'}{'allow site exec command'}= 1;
1404            </Perl>
1405
1406           The above is equivalent to the following ordinary <Host> section:
1407
1408            <Host localhost.localdomain>
1409              ip: 127.0.0.1
1410              allow site exec command: 1
1411            </Host>
1412
1413           You may also assign to the $self variable in order to set variables
1414           directly in the "Net::FTPServer" object itself. This is pretty
1415           hairy, and hence not recommended, but you dig your own hole if you
1416           want. Here is a contrived example:
1417
1418            <Perl>
1419            $self->{version_string} = "my FTP server/1.0";
1420            </Perl>
1421
1422           A cleaner, but more complex way to do this would be to use a
1423           personality.
1424
1425           The <Perl> directive is potentially quite powerful.  Here is a good
1426           idea that Rob Brown had:
1427
1428            <Perl>
1429            my %H;
1430            dbmopen (%H, "/etc/ftpd.db", 0644);
1431            %config = %H;
1432            dbmclose (%H);
1433            </Perl>
1434
1435           Notice how this allows you to crunch a possibly very large
1436           configuration file into a hash, for very rapid loading at run time.
1437
1438           Another useful way to use <Perl> is to set environment variables
1439           (particularly $PATH).
1440
1441            <Perl>
1442            $ENV{PATH} = "/usr/local/bin:$ENV{PATH}"
1443            </Perl>
1444
1445           Here's yet another wonderful way to use <Perl>.  Look in
1446           "/usr/local/lib/ftp/" for a list of site commands and load each
1447           one:
1448
1449            <Perl>
1450
1451            my @files = glob "/usr/local/lib/ftp/*.pl";
1452            my @site_commands;
1453
1454            foreach (@files)
1455             {
1456               push @site_commands, "$1 $_" if /([a-z]+)\.pl/;
1457             }
1458
1459            $config{'site command'} = \@site_commands;
1460
1461            </Perl>
1462
1463           To force a particular version of Net::FTPServer to be used, include
1464           the following code in your configuration file:
1465
1466             <Perl>
1467             die "requires Net::FTPServer version >= 1.025"
1468               unless $Net::FTPServer::VERSION !~ /\..*\./ &&
1469                      $Net::FTPServer::VERSION >= 1.025;
1470             </Perl>
1471
1472   LOADING CUSTOMIZED SITE COMMANDS
1473       It is very simple to write custom SITE commands. These commands are
1474       available to users when they type "SITE XYZ" in a command line FTP
1475       client or when they define a custom SITE command in their graphical FTP
1476       client.
1477
1478       SITE commands are unregulated by RFCs. You may define any commands and
1479       give them any names and any function you wish. However, over time
1480       various standard SITE commands have been recognized and implemented in
1481       many FTP servers. "Net::FTPServer" also implements these. They are:
1482
1483         SITE VERSION      Display the server software version.
1484         SITE EXEC         Execute a shell command on the server (in
1485                           C<Net::FTPServer> this is disabled by default!)
1486         SITE ALIAS        Display chdir aliases.
1487         SITE CDPATH       Display chdir paths.
1488         SITE CHECKMETHOD  Implement checksums.
1489         SITE CHECKSUM
1490         SITE IDLE         Get or set the idle timeout.
1491         SITE SYNC         Synchronize hard disks.
1492
1493       The following commands are found in "wu-ftpd", but not currently
1494       implemented by "Net::FTPServer": SITE CHMOD, SITE GPASS, SITE GROUP,
1495       SITE GROUPS, SITE INDEX, SITE MINFO, SITE NEWER, SITE UMASK.
1496
1497       So when you are choosing a name for a SITE command, it is probably best
1498       not to choose one of the above names, unless you are specifically
1499       implementing or overriding that command.
1500
1501       Custom SITE commands have to be written in Perl. However, there is very
1502       little you need to understand in order to write these commands -- you
1503       will only need a basic knowledge of Perl scripting.
1504
1505       As our first example, we will implement a "SITE README" command.  This
1506       command just prints out some standard information.
1507
1508       Firstly create a file called "/usr/local/lib/site_readme.pl" (you may
1509       choose a different path if you want). The file should contain:
1510
1511         sub {
1512           my $self = shift;
1513           my $cmd = shift;
1514           my $rest = shift;
1515
1516           $self->reply (200,
1517                         "This is the README file for mysite.example.com.",
1518                         "Mirrors are contained in /pub/mirrors directory.",
1519                         "       :       :       :       :       :",
1520                         "End of the README file.");
1521         }
1522
1523       Edit "/etc/ftpd.conf" and add the following command:
1524
1525       site command: readme /usr/local/lib/site_readme.pl
1526
1527       and restart the FTP server (check your system log [/var/log/messages]
1528       for any syntax errors or other problems). Here is an example of a user
1529       running the SITE README command:
1530
1531         ftp> quote help site
1532         214-The following commands are recognized:
1533         214-    ALIAS   CHECKMETHOD     EXEC    README
1534         214-    CDPATH  CHECKSUM        IDLE    VERSION
1535         214 You can also use HELP to list general commands.
1536         ftp> site readme
1537         200-This is the README file for mysite.example.com.
1538         200-Mirrors are contained in /pub/mirrors directory.
1539         200-       :       :       :       :       :
1540         200 End of the README file.
1541
1542       Our second example demonstrates how to use parameters (the $rest
1543       argument). This is the "SITE ECHO" command.
1544
1545         sub {
1546           my $self = shift;
1547           my $cmd = shift;
1548           my $rest = shift;
1549
1550           # Split the parameters up.
1551           my @params = split /\s+/, $rest;
1552
1553           # Quote each parameter.
1554           my $reply = join ", ", map { "'$_'" } @params;
1555
1556           $self->reply (200, "You said: $reply");
1557         }
1558
1559       Here is the "SITE ECHO" command in use:
1560
1561         ftp> quote help site
1562         214-The following commands are recognized:
1563         214-    ALIAS   CHECKMETHOD     ECHO    IDLE
1564         214-    CDPATH  CHECKSUM        EXEC    VERSION
1565         214 You can also use HELP to list general commands.
1566         ftp> site echo hello how are you?
1567         200 You said: 'hello', 'how', 'are', 'you?'
1568
1569       Our third example is more complex and shows how to interact with the
1570       virtual filesystem (VFS). The "SITE SHOW" command will be used to list
1571       text files directly (the user normally has to download the file and
1572       view it locally). Hence "SITE SHOW readme.txt" should print the
1573       contents of the "readme.txt" file in the local directory (if it
1574       exists).
1575
1576       All file accesses must be done through the VFS, not by directly
1577       accessing the disk. If you follow this convention then your commands
1578       will be secure and will work correctly with different back-end
1579       personalities (in particular when ``files'' are really blobs in a
1580       relational database).
1581
1582         sub {
1583           my $self = shift;
1584           my $cmd = shift;
1585           my $rest = shift;
1586
1587           # Get the file handle.
1588           my ($dirh, $fileh, $filename) = $self->_get ($rest);
1589
1590           # File doesn't exist or not accessible. Return an error.
1591           unless ($fileh)
1592             {
1593               $self->reply (550, "File or directory not found.");
1594               return;
1595             }
1596
1597           # Check it's a simple file.
1598           my ($mode) = $fileh->status;
1599
1600           unless ($mode eq "f")
1601             {
1602               $self->reply (550,
1603                             "SITE SHOW command is only supported on plain files.");
1604               return;
1605             }
1606
1607           # Try to open the file.
1608           my $file = $fileh->open ("r");
1609
1610           unless ($file)
1611             {
1612               $self->reply (550, "File or directory not found.");
1613               return;
1614             }
1615
1616           # Copy data into memory.
1617           my @lines = ();
1618
1619           while (defined ($_ = $file->getline))
1620             {
1621               # Remove any native line endings.
1622               s/[\n\r]+$//;
1623
1624               push @lines, $_;
1625             }
1626
1627           # Close the file handle.
1628           unless ($file->close)
1629             {
1630               $self->reply (550, "Close failed: ".$self->system_error_hook());
1631               return;
1632             }
1633
1634           # Send the file back to the user.
1635           $self->reply (200, "File $filename:", @lines, "End of file.");
1636         }
1637
1638       This code is not quite complete. A better implementation would also
1639       check the "retrieve rule" (so that people couldn't use "SITE SHOW" in
1640       order to get around access control limitations which the server
1641       administrator has put in place). It would also check the file more
1642       closely to make sure it was a text file and would refuse to list very
1643       large files.
1644
1645       Here is an example (abbreviated) of a user using the "SITE SHOW"
1646       command:
1647
1648         ftp> site show README
1649         200-File README:
1650         200-README
1651         200-======
1652         200-
1653         200-Biblio@Tech Net::FTPServer - A full-featured, secure, extensible
1654         [...]
1655         200-Copyright (C) 2000-2003 Richard Jones <rich@annexia.org> and other contributors.
1656         200 End of file.
1657
1658   STANDARD PERSONALITIES
1659       Currently "Net::FTPServer" is supplied with three standard
1660       personalities. These are:
1661
1662         Full    The complete read/write anonymous/authenticated FTP
1663                 server which serves files from a standard Unix filesystem.
1664
1665         RO      A small read-only anonymous-only FTP server similar
1666                 in functionality to Dan Bernstein's publicfile
1667                 program.
1668
1669         DBeg1   An example FTP server which serves files to a PostgreSQL
1670                 database. This supports files and hierarchical
1671                 directories, multiple users (but not file permissions)
1672                 and file upload.
1673
1674       The standard Full personality will not be explained here.
1675
1676       The RO personality is the Full personality with all code related to
1677       writing files, creating directories, deleting, etc.  removed. The RO
1678       personality also only permits anonymous logins and does not contain any
1679       code to do ordinary authentication. It is therefore safe to use the RO
1680       personality where you are only interested in serving files to anonymous
1681       users and do not want to worry about crackers discovering a way to
1682       trick the FTP server into writing over a file.
1683
1684       The DBeg1 personality is a complete read/write FTP server which stores
1685       files as BLOBs (Binary Large OBjects) in a PostgreSQL relational
1686       database. The personality supports file download and upload and
1687       contains code to authenticate users against a "users" table in the
1688       database (database ``users'' are thus completely unrelated to real Unix
1689       users). The DBeg1 is intended only as an example. It does not support
1690       advanced features such as file permissions and quotas. As part of the
1691       schoolmaster.net project Bibliotech Ltd. have developed an even more
1692       advanced database personality which supports users, groups, access
1693       control lists, quotas, recursive moves and copies and many other
1694       features. However this database personality is not available as source.
1695
1696       To use the DBeg1 personality you must first run a PostgreSQL server
1697       (version 6.4 or above) and ensure that you have access to it from your
1698       local user account.  Use the "initdb", "createdb" and "createuser"
1699       commands to create the appropriate user account and database (please
1700       consult the PostgreSQL administrators manual for further information
1701       about this -- I do not answer questions about basic PostgreSQL
1702       knowledge).
1703
1704       Here is my correctly set up PostgreSQL server, accessed from my local
1705       user account ``rich'':
1706
1707         cruiser:~$ psql
1708         Welcome to the POSTGRESQL interactive sql monitor:
1709           Please read the file COPYRIGHT for copyright terms of POSTGRESQL
1710
1711            type \? for help on slash commands
1712            type \q to quit
1713            type \g or terminate with semicolon to execute query
1714          You are currently connected to the database: rich
1715
1716         rich=> \d
1717         Couldn't find any tables, sequences or indices!
1718
1719       You will also need the following Perl modules installed: DBI, DBD::Pg.
1720
1721       Now you will need to create a database called ``ftp'' and populate it
1722       with data. This is how to do this:
1723
1724         createdb ftp
1725         psql ftp < doc/eg1.sql
1726
1727       Check that no ERRORs are reported by PostgreSQL.
1728
1729       You should now be able to start the FTP server by running the following
1730       command (not as root):
1731
1732         ./dbeg1-ftpd -S -p 2000 -C ftpd.conf
1733
1734       If the FTP server doesn't start correctly, you should check the system
1735       log file [/var/log/messages].
1736
1737       Connect to the FTP server as follows:
1738
1739         ftp localhost 2000
1740
1741       Log in as either rich/123456 or dan/123456 and then try to move around,
1742       upload and download files, create and delete directories, etc.
1743
1744   SUBCLASSING THE Net::FTPServer CLASSES
1745       By subclassing "Net::FTPServer", "Net::FTPServer::DirHandle" and/or
1746       "Net::FTPServer::FileHandle" you can create custom personalities for
1747       the FTP server.
1748
1749       Typically by overriding the hooks in the "Net::FTPServer" class you can
1750       change the basic behaviour of the FTP server - turning it into an
1751       anonymous read-only server, for example.
1752
1753       By overriding the hooks in "Net::FTPServer::DirHandle" and
1754       "Net::FTPServer::FileHandle" you can create virtual filesystems:
1755       serving files into and out of a database, for example.
1756
1757       The current manual page contains information about the hooks in
1758       "Net::FTPServer" which may be overridden.
1759
1760       See Net::FTPServer::DirHandle(3) for information about the methods in
1761       "Net::FTPServer::DirHandle" which may be overridden.
1762
1763       See Net::FTPServer::FileHandle(3) for information about the methods in
1764       "Net::FTPServer::FileHandle" which may be overridden.
1765
1766       The most reasonable way to create your own personality is to extend one
1767       of the existing personalities. Choose the one which most closely
1768       matches the personality that you want to create. For example, suppose
1769       that you want to create another database personality. A good place to
1770       start would be by copying "lib/Net/FTPServer/DBeg1/*.pm" to a new
1771       directory "lib/Net/FTPServer/MyDB/" (for example). Now edit these files
1772       and substitute "MyDB" for "DBeg1". Then examine each subroutine in
1773       these files and modify them, consulting the appropriate manual page if
1774       you need to.
1775
1776   VIRTUAL HOSTS
1777       "Net:FTPServer" is capable of hosting multiple FTP sites on a single
1778       machine. Because of the nature of the FTP protocol, virtual hosting is
1779       almost always done by allocating a single separate IP address per FTP
1780       site. However, "Net::FTPServer" also supports an experimental IP-less
1781       virtual hosting system, although this requires modifications to the
1782       client.
1783
1784       Normal (IP-based) virtual hosting is carried out as follows:
1785
1786        * For each FTP site, allocate a separate IP address.
1787        * Configure IP aliasing on your normal interface so that
1788          the single physical interface responds to multiple
1789          virtual IP addresses.
1790        * Add entries (A records) in DNS mapping each site's
1791          name to a separate IP address.
1792        * Add reverse entries (PTR records) in DNS mapping each
1793          IP address back to the site hostname. It is important
1794          that both forward and reverse DNS is set up correctly,
1795          else virtual hosting may not work.
1796        * In /etc/ftpd.conf you will need to add a virtual host
1797          section for each site like this:
1798
1799            <Host sitename>
1800
1801              ip: 1.2.3.4
1802              ... any specific configuration options for this site ...
1803
1804            </Host>
1805
1806          You don't in fact need the "ip:" part assuming that
1807          your forward and reverse DNS are set up correctly.
1808        * If you want to specify a lot of external sites, or
1809          generate the configuration file automatically from a
1810          database or a script, you may find the <Include filename>
1811          syntax useful.
1812
1813       There are examples in "/etc/ftpd.conf". Here is how IP-based virtual
1814       hosting works:
1815
1816        * The server starts by listening on all interfaces.
1817        * A connection arrives at one of the IP addresses and a
1818          process is forked off.
1819        * The child process finds out which interface the
1820          client connected to and reverses the name.
1821        * If:
1822            the IP address matches one of the "ip:" declarations
1823            in any of the "Host" sections,
1824          or:
1825            there is a reversal for the name, and the name
1826            matches one of the "Host" sections in the configuration
1827            file,
1828          then:
1829            configuration options are read from that
1830            section of the file and override any global configuration
1831            options specified elsewhere in the file.
1832        * Otherwise, the global configuration options only
1833          are used.
1834
1835       IP-less virtual hosting is an experimental feature. It requires the
1836       client to send a "HOST" command very early on in the command stream --
1837       before "USER" and "PASS". The "HOST" command explicitly gives the
1838       hostname that the FTP client is attempting to connect to, and so allows
1839       many FTP sites to be multiplexed onto a single IP address. At the
1840       present time, I am not aware of any FTP clients which implement the
1841       "HOST" command, although they will undoubtedly become more common in
1842       future.
1843
1844       This is how to set up IP-less virtual hosting:
1845
1846        * Add entries (A or CNAME records) in DNS mapping the
1847          name of each site to a single IP address.
1848        * In /etc/ftpd.conf you will need to list the same single
1849          IP address to which all your sites map:
1850
1851            virtual host multiplex: 1.2.3.4
1852
1853        * In /etc/ftpd.conf you will need to add a virtual host
1854          section for each site like this:
1855
1856            <Host sitename>
1857
1858              ... any specific configuration options for this site ...
1859
1860            </Host>
1861
1862       Here is how IP-less virtual hosting works:
1863
1864        * The server starts by listening on one interface.
1865        * A connection arrives at the IP address and a
1866          process is forked off.
1867        * The IP address matches "virtual host multiplex"
1868          and so no IP-based virtual host processing is done.
1869        * One of the first commands that the client sends is
1870          "HOST" followed by the hostname of the site.
1871        * If there is a matching "Host" section in the
1872          configuration file, then configuration options are
1873          read from that section of the file and override any
1874          global configuration options specified elsewhere in
1875          the file.
1876        * If there is no matching "Host" section then the
1877          global configuration options alone are used.
1878
1879       The client is not permitted to issue the "HOST" command more than once,
1880       and is not permitted to issue it after login.
1881
1882   VIRTUAL HOSTING AND SECURITY
1883       Only certain configuration options are available inside the <Host>
1884       sections of the configuration file.  Generally speaking, the only
1885       configuration options you can put here are ones which take effect after
1886       the site name has been determined -- hence "allow anonymous" is OK
1887       (since it's an option which is parsed after determining the site name
1888       and during log in), but "port" is not (since it is parsed long before
1889       any clients ever connect).
1890
1891       Make sure your default global configuration is secure. If you are using
1892       IP-less virtual hosting, this is particularly important, since if the
1893       client never sends a "HOST" command, the client gets the global
1894       configuration. Even with IP-based virtual hosting it may be possible
1895       for clients to sometimes get the global configuration, for example if
1896       your local name server fails.
1897
1898       IP-based virtual hosting always takes precedence above IP-less virtual
1899       hosting.
1900
1901       With IP-less virtual hosting, access control cannot be performed on a
1902       per-site basis. This is because the client has to issue commands (ie.
1903       the "HOST" command at least) before the site name is known to the
1904       server.  However you may still have a global "access control rule".
1905
1906   ARCHIVE MODE
1907       Beginning with version 1.100, "Net::FTPServer" is able to generate
1908       certain types of compressed and archived files on the fly. In practice
1909       what this means is that if a user requests, say, "file.gz" and this
1910       file does not actually exist (but "file" does exist), then the server
1911       will dynamically generate a gzip-compressed version of "file" for the
1912       user. This also works on directories, so that a user might request
1913       "dir.tar.gz" which does not exist (but directory "dir" does exist), and
1914       the server tars up and compresses the entire contents of "dir" and
1915       presents that back to the user.
1916
1917       Archive mode is enabled by default. However, it will not work unless
1918       you substantially increase the per-process memory, processes and files
1919       limits. The reason for this is that archive mode works by forking
1920       external programs such as "gzip" to perform the compression. For the
1921       same reason you may also need to ensure that at least "gzip",
1922       "compress", "bzip2" and "uuencode" programs are available on the
1923       current $PATH, particularly if you are using a chrooted environment.
1924
1925       To disable archive mode put "enable archive mode: 0" into the
1926       configuration file.
1927
1928       The following file extensions are supported:
1929
1930        .gz      GZip compressed.      Requires gzip program on PATH.
1931        .Z       Unix compressed.      Requires compress program on PATH.
1932        .bz2     BZip2 compressed.     Requires bzip2 program on PATH.
1933        .uue     UU-encoded.           Requires uuencode program on PATH.
1934        .tar     Tar archive.          Requires Perl Archive::Tar module.
1935        .zip     DOS ZIP archive.      Requires Perl Archive::Zip module.
1936        .list    Return a list of all the files in this directory.
1937
1938       File extensions may be combined. Hence ".tar.gz", ".tar.bz2" and even
1939       ".tar.gz.uue" will all work as you expect.
1940
1941       Archive mode is, of course, extensible. It is particularly simple to
1942       add another compression / filter format. In your personality (or in a
1943       <Perl> section in the configuration file) you need to add another key
1944       to the "archive_filters" hash.
1945
1946         $ftps->{archive_filters}{".foo"} = &_foo_filter;
1947
1948       The value of this key should be a function as defined below:
1949
1950         \%filter = _foo_filter ($ftps, $sock);
1951
1952       The filter should return a hash reference (undef if it fails).  The
1953       hash should contain the following keys:
1954
1955         sock      Newly opened socket.
1956         pid       PID of filter program.
1957
1958       The "_foo_filter" function takes the existing socket and filters it,
1959       providing a new socket which the FTP server will write to (for the data
1960       connection back to the client). If your filter is a Unix program, then
1961       the simplest thing is just to define "_foo_filter" as:
1962
1963         sub _foo_filter
1964         {
1965           return $_[0]->archive_filter_external ($_[1], "foo" [, args ...]);
1966         }
1967
1968       The "archive_filter_external" function takes care of the tricky bits
1969       for you.
1970
1971       Adding new generators (akin to the existing tar and ZIP) is more
1972       tricky. I suggest you look closely at the code and consult the author
1973       for more information.
1974

METHODS

1976       Net::FTPServer->run ([\@ARGV]);
1977           This is the main entry point into the FTP server. It starts the FTP
1978           server running. This function never normally returns.
1979
1980           If no arguments are given, then command line arguments are taken
1981           from the global @ARGV array.
1982
1983       $regex = $ftps->wildcard_to_regex ($wildcard)
1984           This is a general library function shared between many of the back-
1985           end database personalities. It converts a general wildcard (eg.
1986           *.c) into a regular expression (eg. ^.*\.c$ ).
1987
1988           Thanks to: Terrence Monroe Brannon <terrence.brannon@oracle.com>.
1989
1990       $regex = $ftps->wildcard_to_sql_like ($wildcard)
1991           This is a general library function shared between many of the back-
1992           end database personalities. It converts a general wildcard (eg.
1993           *.c) into the strange wildcardish format used by SQL LIKE operator
1994           (eg. %.c).
1995
1996       $ftps->reply ($code, $line, [$line, ...])
1997           This function sends a standard single line or multi-line FTP server
1998           reply to the client. The $code should be one of the standard reply
1999           codes listed in RFC 959. The one or more $line arguments are the
2000           (free text) of the reply. Do not include carriage returns at the
2001           end of each $line.  This function adds the correct line ending
2002           format as specified in the RFC.
2003
2004       $ftps->log ($level, $message, ...);
2005           This function is identical to the normal "syslog" function to be
2006           found in "Sys::Syslog". However, it only uses syslog if the "enable
2007           syslog" configuration option is set to true.
2008
2009           Use this function instead of calling "syslog" directly.
2010
2011       $ftps->config ($name);
2012           Read configuration option $name from the configuration file.
2013
2014       $ftps->ip_host_config ($ip_addr);
2015           Look for a <Host> section which contains "ip: $ip_addr".  If one is
2016           found, return the site name of the Host section. Otherwise return
2017           undef.
2018
2019       $filter = $ftps->archive_filter_external ($sock, $cmd [, $args]);
2020           Apply $cmd as a filter to socket $sock. Returns a hash reference
2021           which contains the following keys:
2022
2023             sock      Newly opened socket.
2024             pid       PID of filter program.
2025
2026           If it fails, returns "undef".
2027
2028           See section ARCHIVE MODE elsewhere in this manual for more
2029           information.
2030
2031       $ftps->visit ($dirh, \%functions);
2032           The "visit" function recursively "visits" every file and directory
2033           contained in $dirh (which must be a directory handle).
2034
2035           "\%functions" is a reference to a hash of file types to functions.
2036           For example:
2037
2038             'f' => \&visit_file,
2039             'd' => \&visit_directory,
2040             'l' => \&visit_symlink,
2041             &c.
2042
2043           When a file of the known type is encountered, the appropriate
2044           function is called with $_ set to the file handle. (All functions
2045           are optional: if "visit" encounters a file with a type not listed
2046           in the %functions hash, then that file is just ignored).
2047
2048           The return value from functions is ignored, except for the return
2049           value from the directory ('d') function. The directory function
2050           should return 1 to indicate that "visit" should recurse into that
2051           directory. If the directory function returns 0, then "visit" will
2052           skip that directory.
2053
2054           "visit" will call the directory function once for $dirh.
2055
2056       $sock = $self->open_data_connection;
2057           Open a data connection. Returns the socket (an instance of
2058           "IO::Socket") or undef if it fails for some reason.
2059
2060       $self->pre_configuration_hook ();
2061           Hook: Called before command line arguments and configuration file
2062           are read.
2063
2064           Status: optional.
2065
2066           Notes: You may append your own information to
2067           "$self->{version_string}" from this hook.
2068
2069       $self->options_hook (\@args);
2070           Hook: Called before command line arguments are parsed.
2071
2072           Status: optional.
2073
2074           Notes: You can use this hook to supply your own command line
2075           arguments.  If you parse any arguments, you should remove them from
2076           the @args array.
2077
2078       $self->post_configuration_hook ();
2079           Hook: Called after all command line arguments and configuration
2080           file have been read and parsed.
2081
2082           Status: optional.
2083
2084       $self->post_bind_hook ();
2085           Hook: Called only in daemon mode after the control port is bound
2086           but before starting the accept infinite loop block.
2087
2088           Status: optional.
2089
2090       $self->pre_accept_hook ();
2091           Hook: Called in daemon mode only just before accept(2) is called in
2092           the parent FTP server process.
2093
2094           Status: optional.
2095
2096       $self->post_accept_hook ();
2097           Hook: Called both in daemon mode and in inetd mode just after the
2098           connection has been accepted. This is called in the child process.
2099
2100           Status: optional.
2101
2102       $rv = $self->access_control_hook;
2103           Hook: Called after accept(2)-ing the connection to perform access
2104           control. Detailed request information is contained in the $self
2105           object.  If the function returns -1 then the socket is immediately
2106           closed and no FTP processing happens on it. If the function returns
2107           0, then normal access control is performed on the socket before FTP
2108           processing starts. If the function returns 1, then normal access
2109           control is not performed on the socket and FTP processing begins
2110           immediately.
2111
2112           Status: optional.
2113
2114       $rv = $self->process_limits_hook;
2115           Hook: Called after accept(2)-ing the connection to perform per-
2116           process limits (eg. by using the setrlimit(2) system call). Access
2117           control has already been performed and detailed request information
2118           is contained in the $self object.
2119
2120           If the function returns -1 then the socket is immediately closed
2121           and no FTP processing happens on it. If the function returns 0,
2122           then normal per-process limits are applied before any FTP
2123           processing starts. If the function returns 1, then normal per-
2124           process limits are not performed and FTP processing begins
2125           immediately.
2126
2127           Status: optional.
2128
2129       $rv = $self->authentication_hook ($user, $pass, $user_is_anon)
2130           Hook: Called to perform authentication. If the authentication
2131           succeeds, this should return 0 (or any positive integer >= 0).  If
2132           the authentication fails, this should return -1.
2133
2134           Status: required.
2135
2136       $self->user_login_hook ($user, $user_is_anon)
2137           Hook: Called just after user $user has successfully logged in. A
2138           good place to change uid and chroot if necessary.
2139
2140           Status: optional.
2141
2142       $dirh = $self->root_directory_hook;
2143           Hook: Return an instance of a subclass of Net::FTPServer::DirHandle
2144           corresponding to the root directory.
2145
2146           Status: required.
2147
2148       $self->pre_command_hook;
2149           Hook: This hook is called just before the server begins to wait for
2150           the client to issue the next command over the control connection.
2151
2152           Status: optional.
2153
2154       $rv = $self->command_filter_hook ($cmdline);
2155           Hook: This hook is called immediately after the client issues
2156           command $cmdline, but before any checking or processing is
2157           performed on the command. If this function returns -1, then the
2158           server immediately goes back to waiting for the next command. If
2159           this function returns 0, then normal command filtering is carried
2160           out and the command is processed. If this function returns 1 then
2161           normal command filtering is not performed and the command
2162           processing begins immediately.
2163
2164           Important Note: This hook must be careful not to overwrite the
2165           global $_ variable.
2166
2167           Do not use this function to add your own commands. Instead use the
2168           "$self->{command_table}" and "$self->{site_command_table}" hashes.
2169
2170           Status: optional.
2171
2172       $error = $self->transfer_hook ($mode, $file, $sock, \$buffer);
2173             $mode     -  Open mode on the File object (Either reading or writing)
2174             $file     -  File object as returned from DirHandle::open
2175             $sock     -  Data IO::Socket object used for transfering
2176             \$buffer  -  Reference to current buffer about to be written
2177
2178           The \$buffer is passed by reference to minimize the stack overhead
2179           for efficiency purposes only.  It is not meant to be modified by
2180           the transfer_hook subroutine.  (It can cause corruption if the
2181           length of $buffer is modified.)
2182
2183           Hook: This hook is called after reading $buffer and before writing
2184           $buffer to its destination.  If arg1 is "r", $buffer was read from
2185           the File object and written to the Data socket.  If arg1 is "w",
2186           $buffer will be written to the File object because it was read from
2187           the Data Socket.  The return value is the error for not being able
2188           to perform the write.  Return undef to avoid aborting the transfer
2189           process.
2190
2191           Status: optional.
2192
2193       $self->post_command_hook ($cmd, $rest)
2194           Hook: This hook is called after all command processing has been
2195           carried out on this command. $cmd is the command, and $rest is the
2196           remainder of the command line.
2197
2198           Status: optional.
2199
2200       $self->system_error_hook
2201           Hook: This hook is used instead of $! when what looks like a system
2202           error occurs during a virtual filesystem handle method.  It can be
2203           used by the virtual filesystem to provide explanatory text for a
2204           virtual filesystem failure which did not actually set the real $!.
2205
2206           Status: optional.
2207
2208       $self->quit_hook
2209           Hook: This hook is called after the user has "QUIT" or if the FTP
2210           client cleanly drops the connection. Please note, however, that
2211           this hook is not called whenever the FTP server exits, particularly
2212           in cases such as:
2213
2214            * The FTP server, the Perl interpreter or the personality
2215              crashes unexpectedly.
2216            * The user fails to log in.
2217            * The FTP server detects a fatal error, sends a "421" error code,
2218              and abruptly exits.
2219            * Idle timeouts.
2220            * Access control violations.
2221            * Manual server shutdowns.
2222
2223           Unfortunately it is not in general easily possible to catch these
2224           cases and cleanly call a hook. If your personality needs to do
2225           cleanup in all cases, then it is probably better to use an "END"
2226           block inside your Server object (see perlmod(3)). Even using an
2227           "END" block cannot catch cases where the Perl interpreter crashes.
2228
2229           Status: optional.
2230

BUGS

2232       The SIZE, REST and RETR commands probably do not work correctly in
2233       ASCII mode.
2234
2235       REST does not work before STOR/STOU/APPE (is it supposed to?)
2236
2237       User upload/download limits.
2238
2239       Limit number of clients by host or IP address.
2240
2241       The following commands are recognized by "wu-ftpd", but are not yet
2242       implemented by "Net::FTPServer":
2243
2244         SITE CHMOD   There is a problem supporting this with our VFS.
2245         SITE GPASS   Group functions are not really relevant for us.
2246         SITE GROUP   -"- ditto -"-
2247         SITE GROUPS  -"- ditto -"-
2248         SITE INDEX   This is a synonym for SITE EXEC.
2249         SITE MINFO   This command is no longer supported by wu-ftpd.
2250         SITE NEWER   This command is no longer supported by wu-ftpd.
2251         SITE UMASK   This command is difficult to support with VFS.
2252
2253       Symbolic links are not handled elegantly (or indeed at all) yet.
2254
2255       Equivalent of ProFTPD's ``DisplayReadme'' function.
2256
2257       The ability to hide dot files (probably best to build this into the VFS
2258       layer). This should apply across all commands.  See ProFTPD's
2259       ``IgnoreHidden'' function.
2260
2261       Access to LDAP authentication database (can currently be done using a
2262       PAM module). In general, we should support pluggable authentication.
2263
2264       Log formatting similar to ProFTPD command LogFormat.
2265
2266       More timeouts to avoid various denial of service attacks. For example,
2267       the server should always timeout when waiting too long for an active
2268       data connection.
2269
2270       Support for IPv6 (see RFC 2428), EPRT, EPSV commands.
2271
2272       See also "XXX" comments in the code for other problems, missing
2273       features and bugs.
2274

DEPENDENCY

2276       IO::Dir, IO::stringy
2277

AUTHORS

2279       Richard Jones (rich@annexia.org), Rob Brown (bbb@cpan.org), Keith
2280       Turner (keitht at silvaco.com), Azazel (azazel at azazel.net), and many
2281       others.
2282

MAINTAINER

2284       Ryo Okamoto "<ryo at aquahill dot net>"
2285

REPOSITORY

2287       https://github.com/ryochin/p5-net-ftpserver
2288
2290       Copyright (C) 2000 Biblio@Tech Ltd., Unit 2-3, 50 Carnwath Road,
2291       London, SW6 3EG, UK.
2292
2293       Copyright (C) 2000-2003 Richard Jones (rich@annexia.org) and other
2294       contributors.
2295
2296       This program is free software; you can redistribute it and/or modify it
2297       under the terms of the GNU General Public License as published by the
2298       Free Software Foundation; either version 2 of the License, or (at your
2299       option) any later version.
2300
2301       This program is distributed in the hope that it will be useful, but
2302       WITHOUT ANY WARRANTY; without even the implied warranty of
2303       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
2304       General Public License for more details.
2305
2306       You should have received a copy of the GNU General Public License along
2307       with this program; if not, write to the Free Software Foundation, Inc.,
2308       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
2309

SEE ALSO

2311       Net::FTPServer::Handle(3), Net::FTPServer::FileHandle(3),
2312       Net::FTPServer::DirHandle(3), Net::FTP(3), perl(1), RFC 765, RFC 959,
2313       RFC 1579, RFC 2389, RFC 2428, RFC 2577, RFC 2640, Extensions to FTP
2314       Internet Draft draft-ietf-ftpext-mlst-NN.txt.  Net::FTPServer::XferLog
2315       Test::FTP::Server
2316
2317
2318
2319perl v5.34.0                      2022-01-21                 Net::FTPServer(3)
Impressum