<HTML>
<HEAD>
<TITLE>ncftpspooler(1) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<H2><B>Name</B></H2>
<ul>
<P>
<b>ncftpspooler</b> - Global batch FTP job processor daemon
<P>
</ul>
<H2><B>Synopsis</B></H2>
<ul>
<P>
<B>ncftpspooler</B> -d [<I>options</I>]
<P>
<P>
<B>ncftpspooler</B> -l [<I>options</I>]
<P>
</ul>
<center>
<p>
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_xclick">
<input type="hidden" name="business" value="sales@ncftp.com">
<input type="hidden" name="item_name" value="NcFTP Client">
<input type="hidden" name="item_number" value="NcFTP">
<input type="hidden" name="no_shipping" value="2">
<input type="hidden" name="no_note" value="1">
<input type="hidden" name="currency_code" value="USD">
<input type="hidden" name="tax" value="0">
<input type="hidden" name="bn" value="PP-DonationsBF">
<input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-butcc-donate.gif" border="0" name="submit" alt="Make a donation!">
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>
</center>
<H2><B>Options</B></H2>
<P>
Command line flags:
<ul>
<DL>
<DT><B>-d</B> </DT>
<DD> Begin background processing of FTP jobs in the
designated FTP job queue directory.
<P>
</DD>
<DT><B>-q</B> <I>XX</I> </DT>
<DD>Use this option to specify a directory to use as
the FTP job queue instead of the default directory,
<tt>/var/spool/ncftp</tt>.
<P>
</DD>
<DT><B>-o</B> <I>XX</I> </DT>
<DD>Use this option to specify a filename to use as
the log file. By default, (and rather inappropriately)
the program simply uses a file called <I>log</I>
in the job queue directory. If you don't want a
log, use this option to specify
<tt>/dev/null</tt>.
<P>
</DD>
<DT><B>-l</B> </DT>
<DD> Lists the contents of the job queue directory.
<P>
</DD>
<DT><B>-s</B> <I>XX</I> </DT>
<DD>When the job queue is empty, the program sleeps
120 seconds and then checks again to see if a new
job has been submitted. Use this option to change
the number of seconds used for this delay.
<P>
</DD>
</DL>
</ul>
<H2><B>Description</B></H2>
<P>
The <I>ncftpspooler</I> program evolved from the <I>ncftpbatch</I> program.
The <I>ncftpbatch</I> program was originally designed as a
``personal FTP spooler'' which would process a single
background job a particular user and exit when it finished;
the <I>ncftpspooler</I> program is a ``global FTP
spooler'' which stays running and processes background
jobs as they are submitted.
<P>
<P>
The job queue directory is monitored for specially-named
and formatted text files. Each file serves as a single
FTP job. The name of the job file contains the type of
FTP job (<I>get</I> or <I>put</I>), a timestamp indicating the earliest
the job should be processed, and optionally some additional
information to make it easier to create unique job
files (i.e. a sequence number). The contents of the job
files have information such as the remote server machine
to FTP to, username, password, remote pathname, etc.
<P>
<P>
Your job queue directory must be readable and writable by
the user that you plan to run <I>ncftpspooler</I> as, so that
jobs can be removed or renamed within the queue.
<P>
<P>
More importantly, the user that is running the program
will need adequate privileges to access the local files
that are involved in the FTPing. I.e., if your spooler is
going to be processing jobs which upload files to remote
servers, then the user will need read permission on the
local files that will be uploaded (and directory access
permission the parent directories). Likewise, if your
spooler is going to be processing jobs which download
files, then the user would need to be able to write to the
local directories.
<P>
<P>
Once you have created your spool directory with appropriate
permissions and ownerships, you can run
<I>ncftpspooler</I> <I>-d</I> to launch the spooler daemon. You can run
additional spoolers if you want to process more than FTP
job from the same job queue directory simultaneously. You
can then monitor the log file (i.e., using <tt>tail -f</tt> ) to
track the progress of the spooler. Most of the time it
won't be doing anything, unless job files have appeared in
the job queue directory.
<P>
<H2><B>Job File Names</B></H2>
<P>
When the <I>ncftpspooler</I> program monitors the job queue
directory, it ignores any files that do not follow the
naming convention for job files. The job files must be
prefixed in the format of <I>X-YYYYMMDD-hhmmss</I> where <I>X</I>
denotes a job type, <I>YYYY</I> is the four-digit year, <I>MM</I> is the
two-digit month number, <I>DD</I> is the two-digit day of the
month, <I>hh</I> is the two-digit hour of the day (00-23), <I>mm</I> is
the two-digit minute, and <I>ss</I> is the two-digit second. The
date and time represent the earliest time you want the job
to be run.
<P>
<P>
The job type can be <I>g</I> for a get (download from remote
host), or <I>p</I> for aput (upload to remote host).
<P>
<P>
As an example, if you wanted to schedule an upload to
occur at 11:45 PM on December 7, 2001, a job file could be
named
<P>
<ul>
<tt>p-20011207-234500</tt>
</ul>
<P>
In practice, the job files include additional information
such as a sequence number or process ID. This makes it
easier to create unique job file names. Here is the same
example, with a process ID and a sequence number:
<P>
<ul>
<tt>p-20011207-234500-1234-2</tt>
</ul>
<P>
When submitting job files to the queue directory, be sure
to use a dash character after the <I>hhmmss</I> field if you
choose to append any additional data to the job file name.
<P>
<H2><B>Job File Contents</B></H2>
<P>
Job files are ordinary text files, so that they can be
created by hand. Each line of the file is a key-pair in
the format <I>variable</I>=<I>value</I>, or is a comment line beginning
with an octothorpe character (<I>#</I>), or is a blank line.
Here is an example job file:
<P>
<ul>
<pre>
# This is a NcFTP spool file entry.
job-name=g-20011016-100656-008299-1
op=get
hostname=ftp.freebsd.org
xtype=I
passive=1
remote-dir=pub/FreeBSD
local-dir=/tmp
remote-file=README.TXT
local-file=readme.txt
</pre>
</ul>
<P>
Job files are flexible since they follow an easy-to-use
format and do not have many requirements, but there are a
few mandatory parameters that must appear for the spooler
to be able to process the job.
<P>
<UL><DL>
<DT><I>op</I></DT>
<DD>
The operation (job type) to perform. Valid values
are <I>get</I> and <I>put</I>.
</DD>
<P>
<DT><I>hostname</I></DT>
<DD>
The remote host to FTP to. This may be an IP
address or a DNS name (i.e. ftp.example.com).
</DD>
</DL></UL>
<P>
For a regular <I>get</I> job, these parameters are required:
<UL><DL>
<DT><I>remote-file</I></DT>
<DD>
The pathname of the file to download from the
remote server.
</DD>
<P>
<DT><I>local-file</I></DT>
<DD>
The pathname to use on the local server for the
downloaded file.
</DD>
</DL></UL>
<P>
For a regular <I>put</I> job, these parameters are required:
<P>
<UL><DL>
<DT><I>local-file</I></DT>
<DD>
The pathname of the file to upload to the remote
server.
</DD>
<P>
<DT><I>remote-file</I></DT>
<DD>
The pathname to use on the remote server for the
uploaded file.
</DD>
</DL></UL>
<P>
For a recursive <I>get</I> job, these parameters are required:
<P>
<UL><DL>
<DT><I>remote-file</I></DT>
<DD>
The pathname of the file or directory to download
from the remote server.
</DD>
<P>
<DT><I>local-dir</I></DT>
<DD>
The directory pathname to use on the local server
to contain the downloaded items.
</DD>
</DL></UL>
<P>
For a recursive <I>put</I> job, these parameters are required:
<P>
<UL><DL>
<DT><I>local-file</I></DT>
<DD>
The pathname of the file or directory to upload to
the remote server.
</DD>
<P>
<DT><I>remote-dir</I></DT>
<DD>
The directory pathname to use on the remote server
to contain the uploaded items.
</DD>
</DL></UL>
<P>
The rest of the parameters are optional. The spooler will
attempt to use reasonable defaults for these parameters if
necessary.
<P>
<UL><DL>
<DT><I>user</I> </DT>
<DD> The username to use to login to the remote server.
Defaults to ``anonymous'' for guest access.
</DD>
<P>
<DT><I>pass</I> </DT>
<DD> The password to use in conjunction with the username
to login to the remote server.
</DD>
<P>
<DT><I>acct</I> </DT>
<DD> The account to use in conjunction with the username
to login to the remote server. The need to
specify this parameter is extremely rare.
</DD>
<P>
<DT><I>port</I> </DT>
<DD> The port number to use in conjunction with the
remote hostname to connect to the remote server.
Defaults to the standard FTP port number, 21.
</DD>
<P>
<DT><I>host-ip</I></DT>
<DD>
The IP address to use in conjunction with the
remote hostname to connect to the remote server.
This parameter can be used in place of the <I>host</I><B>_</B>n<I>ame</I>
parameter, but one or the other must be used.
This parameter is commonly included along with the
<I>hostname</I> parameter as supplemental information.
</DD>
<P>
<DT><I>xtype</I></DT>
<DD>
The transfer type to use. Defaults to binary
transfer type (TYPE I). Valid values are <I>I</I> for
binary, <I>A</I> for ASCII text.
</DD>
<P>
<DT><I>passive</I></DT>
<DD>
Whether to use FTP passive data connections (PASV)
or FTP active data connections (PORT). Valid values
are <I>0</I> for active, <I>1</I> for passive, or <I>2</I> to try
passive, then fallback to active. The default is
<I>2</I>.
</DD>
<P>
<DT><I>recursive</I></DT>
<DD>
This can be used to transfer entire directory
trees. By default, only a single file is transferred.
Valid values are <I>yes</I> or <I>no</I>.
</DD>
<P>
<DT><I>delete</I></DT>
<DD>
This can be used to delete the source file on the
source machine after successfully transferring the
file to the destination machine. By default,
source files are not deleted. Valid values are
<I>yes</I> or <I>no</I>.
</DD>
<P>
<DT><I>job-name</I></DT>
<DD>
This isn't used by the program, but can be used by
an entity which is automatically generating job
files. As an example, when using the <I>-bbb</I> flag
with <I>ncftpput</I>, it creates a job file on stdout
with a <I>job-name</I> parameter so you can easily copy
the file to the job queue directory with the suggested
job name as the job file name.
</DD>
<P>
<DT><I>pre-ftp-command</I><BR>
<I>post-ftp-command</I></DT>
<DD>
These parameters correspond to the <I>-W</I>, and <I>-Y</I>
options of <I>ncftpget</I> and <I>ncftpput</I>. It is important
to note that these refer to RFC959 File Transfer
Protocol commands and <B>not</B> shell commands, nor commands
used from within <tt>/usr/bin/ftp</tt> or <i>ncftp</i>.
</DD>
<P>
<DT><I>pre-shell-command</I><BR>
<I>post-shell-command</I></DT>
<DD>
These parameters provide hooks so you can run a
custom program when an item is processed by the
spooler. Valid values are pathnames to scripts or
executable programs. Note that the value must not
contain any command-line arguments -- if you want
to do that, create a shell script and have it run
your program with the command-line arguments it
requires.
</DD>
</DL></UL>
<P>
Generally speaking, <I>post-shell-command</I> is much more useful
than <I>pre-shell-command</I> since if you need to use these
options you're more likely to want to do something after
the FTP transfer has completed rather than before. For
example, you might want to run a shell script which pages
an administrator to notify her that her 37 gigabyte file
download has completed.
<P>
<P>
When your custom program is run, it receives on standard
input the contents of the job file (i.e. several lines of
<I>variable</I>=<I>value</I> key-pairs), as well as additional data the
spooler may provide, such as a <I>result</I> key-pair with a textual
description of the job's completion status.
<P>
<P>
<I>post-shell-command</I> update a log file named
<tt>/var/log/ncftp_spooler</tt>.
<ul>
<pre>
#!/usr/bin/perl -w
use strict;
my ($line);
my (%params) = ();
while (defined($line = <STDIN>)) {
$params{$1} = $2 if ($line =~ /^([^=\#\s]+)=(.*)/);
}
if ((defined($params{"result"})) && ($params{"result"} =~ /^Succeeded/)) {
open(LOG, ">> /var/log/ncftp_spooler.log") or exit(1);
print LOG "DOWNLOAD" if ($params{"op"} eq "get");
print LOG "UPLOAD" if ($params{"op"} eq "put");
print LOG " ", $params{"local-file"}, "\n";
close(LOG);
}
</pre>
</ul>
<H2><B>Diagnostics</B></H2>
<P>
The log file should be examined to determine if any <I>ncftpspooler</I>
processes are actively working on jobs. The log
contains copious amounts of useful information, including
the entire FTP control connection conversation between the
FTP client and server.
<P>
<H2><B>Bugs</B></H2>
<P>
The <I>recursive</I> option may not be reliable since <I>ncftpspooler</I>
depends on functionality which may or may not be
present in the remote server software. Additionally, even
if the functionality is available, <I>ncftpspooler</I> may need
to use heuristics which cannot be considered 100% accurate.
Therefore it is best to create individual jobs for
each file in the directory tree, rather than a single
recursive directory job.
<P>
<P>
For resumption of downloads to work, the remote server
must support the FTP <I>SIZE</I> and <I>MDTM</I> primitives. Most modern
FTP server software can do this, but there are still a
number of bare-bones <I>ftpd</I> implementations which do not.
In these cases, <I>ncftpspooler</I> will re-download the file in
entirety each time until the download succeeds.
<P>
<P>
The program needs to be improved to detect jobs that have
no chance of ever completing successfully. There are
still a number of cases where jobs can get spooled but get
retried over and over again until a vigilant sysadmin manually
removes the jobs.
<P>
<P>
The spool files may contain usernames and passwords stored
in cleartext. These files should not be readable by any
user except the user running the program!
<P>
<H2>Author</H2>
<blockquote>
<P>
Mike Gleason, <a href="http://www.ncftp.com">NcFTP Software</a>.
</blockquote>
<H2>See Also</H2>
<blockquote>
<P>
<I>ncftpput(1)</I>, <I>ncftpget(1),</I>
<I>ncftp(1)</I>, <I>ftp(1)</I>, <I>rcp(1)</I>, <I>tftp(1)</I>. <P>
<I>LibNcFTP</I> (<a href="http://www.ncftp.com/libncftp/">http://www.ncftp.com/libncftp/</a>).
</blockquote>
</BODY></HTML>
