|
DSFTP
|
DSFTP
DSFTP is a full-fledged FTP server, with the additional
ability to boot .nds files directly from the FTP prompt (currently
only tested on SuperCard CF and SD, but should work on most).
DSFTP is a stand-alone program that you can use to run a FTP
server on your DS. It is also a software component that makes it
easy for you to add an FTP server to your own program with a
couple lines of code. With this, you can speed up the build
process radically, because you can upload the new version of
your program to your own running program, and reboot it
immediately. This can even be automated via the command line. No
swapping of flash cards ever again! Please refer to the
Development section of this document for a quick
introduction.
The downloadable archive (get
it here) contains the following:
- The compiled .nds and .ds.gba files of the stand-alone
DSFTP server
- The library and headers for the DSFTP software
component
- Full documentation in PDF and RTF format
- The full source code for the stand-alone server program,
as an example for how to use the software component
|
Screenshot
|
|
Disclaimer
DISCLAIMER: This software is provided as-is, without any
express or implicit warranty. Don't expect too much, and don't
blame me if it wrecks your flash cart, sets your house on fire
and rapes your dog. You have been warned.
That said, it's reasonably well-behaved here :-) Please send me
your experiences with DSFTP via
per email (replace
_AT_ by @). Thank you!
News
Version 2.4
Changes:
The FAT driver
has been upgraded to
chishm's
DLDI file
system driver interface.
The precompiled version comes with Supercard CF driver installed.
No other interfaces will be supported any more. If you
have a different flash card, please patch the DSFTP binary yourself.
Version 2.3
Changes:
- UNZP added (submitted by Bertrand Augereau)
- DS->PC file transfer speeded up a lot (patch to DSWifi submitted by masscat)
- Linked with Devkit R18 again (fixes some showstopper bugs)
- More bugfixes
For older news, see the documentation.
Installation
Download a version of DSFTP here:
Unzip it, copy the DSFTP.nds (or .ds.gba) file to your flash
card, and have fun!
For development, it's best to copy libDSFTP.a and libDSFTPd.a to
your devkitpro's lib directory, and the include directory to
your devkitpro's include dir.
Using the stand-alone server
This section describes how to setup, configure and use the
stand-alone DSFTP server.
Configuration
DSFTP reads its settings from a configuration file, which must
exist at /data/settings/ftp.conf. Users who may logon are defined
in this file, and there are no default users hard-coded, so the
file is required. Here is an example of a configuration file:
motd /ftp/motd.txt
logfile /data/logs/ftp.log
loglevel 4
timeout 60
portrangestart 9000
portrangeend 9999
screensaver 30
wakeonlog false
user bjoern
pass whatever
root /
home /
write true
boot true
end user
user anonymous
root /ftp/anonymous
write false
end user
Whitespace in the configuration file is ignored (the
indents in the example file are purely cosmetic), as are empty
lines and lines starting with "#". The following settings are
valid:
motd FILE
Defines a file that contains the message of the day, which will be
printed on logon.
logfile FILE
Defines the name of a file to store log messages in.
loglevel LEVEL
Only messages with a loglevel below LEVEL will be printed / logged
to file. LEVEL ranges from 0 (critical) to 5 (informational).
masquerade NAME
Specifies that the server masquerades as the host NAME. This is
very useful if the server is behind a NAT gateway, and its actual
IP address is not visible to the world. In this case, for clients
using PASV instead of EPSV for the passive mode, the reply to PASV
will contain the IP address for NAME, not the actual server's IP.
Note: Do not use this if you're not behind a NAT gateway and the
server is not actually reachable under the given name. It won't
work.
timeout SECONDS
Specifies that the server will close the data connection after the
given period of inactivity. Default is 60 seconds.
portrangestart NUM / portrangeend NUM
Specifies what port range to use for passive connections. If these
aren't given, the portrange goes from 1024 to INT_MAX.
screensaver SECONDS
Specifies the timeout for the screen saver. Can also be the string
"off", which disables the screen saver altogether. Default is 60
seconds.
wakeonlog BOOL
If this is "true", the screensaver will wake up on every log
entry. Default is true.
user NAME
Starts a new user block, which must be finished by "end
user". Only users named by a user block will be accepted for
login. Exception: If no users at all are specified, a default user
and pass are generated automatically and displayed in the log.
Settings valid in the user block are:
pass PASSWORD
Set the password for the current user, stored in cleartext. If the
user's name is "anonymous", this will be ignored, and the user
will be asked to specify his email address for a password.
root DIR
Restrict the user to the directory hierarchy below DIR.
home DIR
Upon logon, set the current directory to DIR (relative to the
user's root dir).
write BOOL
Grant the user write permission (including permission to rename
and delete!) for everything below his root dir.
boot BOOL
Grant the user permission to boot files and to power down the DS.
Protocol Additions
DSFTP defines the additional command "BOOT", with the filename to
be booted as an argument. Since the "BOOT" command is not in the
official protocol, the FTP client doesn't know it. For text-based
ftp, the "quote" prefix allows you to send it anyway, like this:
quote BOOT /mydsfile.nds
Possible reply codes to the BOOT command are 530 (No permission to
boot) and 250 (Booting file). Booting currently only works on
Supercard CF. No checks are performed; it is legal to boot a
".txt" file, which will most likely crash your DS. On a successful
boot, the data connection to the client is closed. Since booting
doesn't return on success, a success message is always printed. If
the file to boot could not be found, nothing is reported to the
FTP client, but the connection remains intact.
DSFTP defines the additional command "POWR", which can be used to
power the DS off. Possible reply codes are 530 (No permission to
power off) and 250 (Powering off).
DSFTP defines the additional command "UNZP" to uncompress files
compressed with GNU zip. Usage is:
quote UNZP /zipfile.gz
This will create a file named /zipfile (without the .gz
ending). The original, zipped file will not be removed. Possible
reply codes are 530 (Unable to open file or error unpacking) and
226 (unpacking succeeded.
Using DSFTP for development
This section describes how you can use libDSFTP to add an FTP
server to your own applications. For all of these steps, you can
use the included source for DSFTP as an example.
Preliminaries
Adding an FTP server is very easy. First, you should make sure
that the following components are added to your build
process. That means their include files must be accessible, and
their libraries/object files must be linked with your program.
- gba_nds_fat (either chishm's FAT lib or REIN's)
- dswifi
- libDSFTP
Then, you initialize the Wifi and FAT libraries as usual. Please
refer to their respective examples for info on how to do it, or to
the DSFTP source.
Creating the server
Next, you create an instance of BFTPServer somewhere in your
program, like so:
BFTPServer server;
If you want to, you can also create an instance of
BFTPConfigurator to configure the server. This is not mandatory,
but it allows you to configure the FTP server via config
file. This would look as follows.
BFTPConfigurator configurator(&server;);
configurator.configureFromFile("/data/settings/ftp.conf");
...or wherever you want the config file to be.
If you do not use a BFTPConfigurator, you must add users to the
FTP server manually. Otherwise, you won't be able to log in. The
simplest way to do this is like this:
server.addUser("myusername", "mypassword");
Please refer to BFTPServer.h for other arguments to this
command.
Letting it do its work
That's it, your FTP server is ready! Now, whenever your program is
idle (e.g. from the main loop), you should let the server do its
work, like this:
server.handle();
Wrapping it up
And that's all you have to do. All the code inside of a nice
little mainloop function would look like this:
void mainloop(void)
{
BFTPServer server;
BFTPConfigurator configurator(&server;);
configurator.configureFromFile("/data/settings/ftp.conf");
while(true)
{
server.handle();
swiWaitForVBlank();
}
}
Please refer to the source code of DSFTP and the header files of
libDSFTP for other possible settings and features.
Known Bugs and Limitations
The following bugs and limitations are known at the time of
writing:
- Sometimes sockets seem not to be reaped correctly.
If any bugs pop up, please send me the log output with a full
description to [email protected]. Thank you and have fun!
Is DSFTP useful for you as a
development tool or as a way of pushing data to your DS? Do you
want me to continue working on DS apps? If so, I will happily
accept a donation
-- whatever amount you think acceptable. My PayPal account is the
same as my email address.
Current donations will go toward the purchase of a DS Lite card
adapter, probably an EZ4 or SC lite, and a fitting memory
card.
You can also donate something from my
Amazon
wishlist!