Uplink Communication Server


BE AWARE: By now there is no public release of uplink. Before use the current development version, please read the various warnings along this document (for instance the section on security .

This page documents the (yet unreleased) version 0.9g of uplink. You'll find the documentation for version 0.9f within the 0.9f tar distribution.

uplink is a full-featured dialup communication server designed for a small office, that provides integrated email, fax and Internet access facilities for a small LAN. The communication features are provided by robust and independent components (pppd, sendmail, qmail, fetchmail, samba, getty, efax, sendfax and others), managed by a server written in perl. The server may be controlled from any LAN client through a text-based telnet session or a graphic win32 client. The entire package is distributed under the terms of the GNU GPL.

Contents

1. Introduction

2. LAN set-up

3. Uplink installation

4. The email server

5. The fax server

6. Mirroring files and web pages from the Internet

7. Dialin support

8. Miscellaneous

1. Introduction

These pages document uplink, a network server that integrates the features of various softwares in order to build a versatile dialup communication server for a small LAN. All computers on the LAN may rely on this server for sending and receiving emails, access the Web and send faxes. The main benefit provided by uplink is to save human time and communication resources, and this is achieved by:

The scenario faced by uplink is that of the small and very small offices. It's currently being used in offices with 1 to 30 people, where one dialup link suffices for the communication needs. By now uplink is able to handle one shared line for data and fax (and perhaps voice) or one line for data and one for fax.

1.1 The uplink server

The major component of the uplink package is the "uplink" perl script. Once started by the system boot scripts, it waits events and performs actions in response to them. Most of these events are commands received from the LAN through some client interface. Three client interfaces are available: a command-line one, useful to issue command through at or cron, a text-based one and a graphical one (currently limited to win32 platforms). A complete reference of these commands is available. These commands include but are not limited to:

These commands may be issued by cron jobs through uplcmd. A fax submitted by a LAN client through a samba print queue is another kind of event that uplink waits for. In this case, it will start the fax delivery process as explained later.

For the sake of the document intelligibility, it's important to distinguish clearly the uplink script from the computer where it's running, so we will avoid the generic term "server". The term uplink will refer the perl script, while the term DCS (Dialup Communication Server) will refer the computer.

1.2 The Email Server

The DCS acts as an offline SMTP/POP/IMAP server for the LAN clients. So each LAN machine will be configured to use it as SMTP/POP/IMAP server. Therefore emails generated in these clients will be sent to the DCS. It will deliver immediately local emails while non-local emails will be queued for later (batch) processing.

Emails from remote senders will be periodically fetched by the DCS from all specified remote mailboxes, and put on local mailboxes, where they will be available for LAN clients through POP/IMAP.

Currently uplink supports both sendmail and qmail as mail transport agents. One and only one of them must be chosen if email services are desired. The advantages of sendmail are basically two: it's usually pre-packaged in free Unices, and it supports multi-rcpt when transferring emails to the ISP smtp server (so if you send an email with a large file attached for various recipients, it will be sent only once through your dialed line). On the other side, qmail is reputed as faster than sendmail.

The choice of the MTA will determine the choice of the POP/IMAP server, because sendmail and qmail use different mailbox formats (the term "mailbox" does not have in this document the strict sense of "unix mailbox"). This will also impact the choice of the mail clients that will run directly on the DCS (if any).

1.3 The Fax Server

The DCS offers a fax queue to the LAN clients. Faxes are submitted through an lpd print queue exported by samba to windows clients. Many fax operations are available (resend, preview, etc), through the client interfaces.

This fax queue is directly managed by uplink. When a LAN client submits a fax, the DCS print filter moves the job to the fax spool. Then uplink detects it, and tries to contact the client interface of the LAN client that generated the fax, in order to ask for the fax recipients. Once obtained the recipients, the fax becomes able to be delivered as soon as the line becomes idle.

Windows clients may submit the fax in postscript format. Currently no windows print driver is provided by the uplink package, but some native windows drivers are known to produce output compatable with the filters that generate the fax pages on the DCS (check the details on later sections).

Both efax and sendfax are supported as fax delivery agents (warning: sendfax support is currently broken). If your faxmodem is class 1 only, you'll need to use efax, otherwise you can choose efax or sendfax.

1.4 Other features

The DCS connects under request to the Internet, and shares the connection with the LAN clients, that can use Internet interactive services through IP masquerading and/or proxy services. Both the connection and the disconnection requests may be manually issued through the client interface, or managed directly by pppd options like idle (note: demand dialling is not currently supported).

If desired, the DCS may offer a web proxy server to the LAN clients, as well as a common cache shared by all clients. Various web proxies are freely available and may be used, for instance the Apache httpd server is also a web proxy. The wwwoffle proxy has specific support on uplink.

As specific times, uplink will connect to the ISP and download files and/or web pages as requested. This feature may be used for instance to automatically download and maintain on the DCS news pages that are updated on a daily basis, or to manage the download of some large archive that will require, say, three or four nights to be completed.

No lock on the modem port is performed by uplink, so you can use the line (for instance running on it any communication software) when it is idle. An alternative is to enable the dialin support. In this case, when the line becomes idle, uplink will run a getty command on it, in order to serve incoming data/fax/voice calls (the getty process will be killed by uplink when someone requests the line)

1.5 The history of uplink

In the beginning of 98, with the help of some friends, we started writing a Linux Howto on Linux and small offices. At the time, Greg Hankins approved the idea. However, our focus was only the communication facilities that could be provided by Linux on a small office, so the name was not adequate. Furthermore, even restricting ourselves to communication, it's hard to write a useful document because the theme is too vast.

After a suggestion from Andre Wolff, in the mid of 98 we started writing uplink, and it quickly became clear that this software could be a useful contribution for small offices using free software, and it could also be a basis to introduce various important communication softwares that are somewhat hard to learn (basically those supported by uplink).

From there to now, uplink is growing on features as required (and possible), and its documentation is being written both to be used as a tutorial on uplink, and to introduce so many nice and useful softwares.

2. LAN set-up

This document intends to be self-contained, so we'll need to discuss the configuration of the communication softwares managed by uplink. As these softwares are covered in great detail by other documents, we'll adopt a very pragmatic approach, and limit ourselves to present some example configurations and test procedures, adding comments or quick explanations.

If you're an experienced systems manager, maybe at some points you'll prefer your own feeling than our suggestions. Furthermore, if you do not need the entire uplink features, or if the installation is being done over an already functional tcpip LAN, some of these sections may be skiped.

2.1 LAN tcpip configuration

to be written

note on IP forwarding (to be written)

2.2 Choosing the DCS Hardware

FYI: almost any recent PC will fit these recommendations.

Basically you need a computer able to run any supported system (Currently Linux or FreeBSD), with a faxmodem. In practice, we suggest as minimal configuration a 486 DX4 PC with 16M RAM and a 540M disk. A recommended configuration would be a P100 with 32M RAM and 1G disk. Processing power is required to convert graphics (postscript to tiffg3, tiffg3 to windows bitmap, etc), so a faster CPU (P200 or better), may be a good choice.

It's convenient to choose a faxmodem supporting v42bis on the data portion and class 2 on the fax portion. While almost all newer faxmodems support v42bis, many of them are class 1 only, but don't worry, you can live without class 2. In any case, try to avoid a high load or a high interrupt rate on the CPU, or serial communication may become compromised.

In order to avoid a high interrupt rate, it's a good idea to use a SCSI disk controller or an IDE disk controller that supports DMA, mainly if you plan to use the computer as disk and/or print server too (note that the controller DMA features must be supported by the operating system). Intel FX/HX/VX/TX series is probably ok. I'm not sure about clones (VXpro, TXpro), but it seems that they're supported by newer (2.2.x) Linux kernels.

Yet uplink may be used on an standalone computer, generally it will provide communication features for a LAN, so you'll need a network card and cables too. Keyboard, mouse and monitor may not be present.

The author uses or used uplink in a variety of hardwares:

Remember to check if a hardware piece is supported by your operating system before buy it, and try to avoid PnP-only cards if you're not familiar with them.

2.3 Basic System Installation

In order to use uplink you need a box with some supported system (Linux and FreeBSD are used by the author) and required software components installed:

2.4 Configuring bind for a private network

At this point we're supposing that your LAN is physically built and TCP/IP is correctly configured on all machines. Sometimes this may not be easy to do, but at present these notes will not help you to make that, except by the nameserver configuration. Samba requires a working nameserver for you LAN, so you'll need to set-up bind.

The nameserver configuration relies on an already-done choice for IP numbers. Small (and large) internal networks usually may be configured to use fixed IP numbers from reserved ranges (networks 10, 172.16 and 192.168), so we'll suppose that this is the case. An internal domain name must be chose. This domain name may be your organization's official domain name (like foo.com or foo.org), or a totally unofficial one, like office.mynet.

When using internally an official Internet domain, the only additional care that must be taken is to map on the internal nameserver the official IP numbers assigned to that domain. For instance, if the web pages of your corporation foo.com are hosted by a service provider, than the name www.foo.com will need to be resolved to its official number by the internal nameserver.

An example configuration, for bind version 4 is included on the distribution. The file named.boot is read by named on startup. It usually must reside at /etc. All other files may be put elsewhere, on the directory given within named.boot. In order to be able to resolve external names, the file named.cache must bring information on the root nameservers. It must be slightly changed in order to include the domain and network use internally (see the example). Finally, the remaining files contain direct and reverse resolution information.

Don't forget that bind must be installed and must be started on boot. If your platform uses a version 8 bind, the syntax of the files will be a bit more complex than those provided as example on the distribution.

2.5 Security recommendations

Once the DCS gets connected to the ISP, it becomes accessible for potencially any Internet computer. If someone succeeds in breaking the DCS security, the LAN security will become compromised. So it's convenient to perform some preventive actions, in order to avoid undesirable events.

[packet filtering (to be written)]

[disabling or restricting access to inetd services (to be written)]

[note on viruses (to be written)]

2.6 Building the chat scripts

Valuable documentation is available on pppd configuration, so we'll only present some very practical directions. The goal of this section is to build a working version of the parameters and configuration files required to stablish a ppp connection with your ISP. If these parameters and files are already available, skip this section and go to the next one.

Most ISPs offer ready-to-use scripts and support information for clients using unix-like systems with pppd. Please check if this is your case, because you'll save time and perhaps avoid headaches.

Serial port configuration

First of all, you must make sure that the serial port is correctly configured, that is, it must be assigned to it an IO address and an IRQ number (we'll cover only the configuration of the PC "native" ports COM1-4), and the operating system must be aware of these parameters.

Most internal faxmodems are PnP, and some of them are PnP-only. In order to use a PnP device, it the device must be configured by the motherboard BIOS or by some speciic software, like the isapnptools package. Once configured, the kernel must detect the port, and the IRQ number (if not standard) must be informed to the operating system. You can check if these steps were correctly performed throug a simple test using any communication package, like minicom or seyon (all these steps are carefully descibed in our specific documentation ).

The pppd command

In order to make a ppp connection to the ISP, some parameters must be provided to pppd. These parameters include the serial port to use and its configuration, the commands that will drive the modem to dial the ISP, how to proceed to authenticate, and perhaps some additional rules for IP-related stuff. Part of these parameters will be specified by the pppd options file. Others will be specified on the command line. In order to make easier to change them, uplink prefers to put few of them on the options file. The command line currently used by uplink to start pppd is as follows:

    # pppd ttyS1 38400 idle 60 nodetach connect 'chat -f script'

In this case we're using the port COM2 at 38400. The link must be dropped after 60 seconds of inactivity, and the file "script" contains the dialog that will reset the modem, dial the ISP, and, perhaps, authenticate the user. These parameters are specified to uplink through the uplink.cf file, and some of them may be dinamically changed.

Testing pppd by hand with type-in authentication

So, to make sure that this will work, it's a good idea to start that command by hand on the shell prompt, but before that it's necessary to create the pppd options file (/etc/ppp/options) and the chat script. In this case, the options file may be as simple as the following:

    lock
    crtscts
    defaultroute

A very simple version for the script file follows. It's designed for an authentication process where the ISP prompts the user, expecting its username and password to be typed by hand. The number 1234567 must be replaced by the ISP number, and the strings "foo" and "mysecret" must be replaced by the actual username and password.

    "" ATZ OK ATM1L0 OK ATD1234567
    CONNECT ""
    ogin foo ssword mysecret

Of course your mileage may vary. For instance, may happen that the strings used by the ISP to prompt you are not just "login:" and "password:", so in this case it will be necessary to replace them on the script. In some cases may be necessary type some command after the authentication in order to start ppp on the ISP side. This can be accomplished by adding a new line with a pair or strings like

    "" ppp

Where "ppp" is the command. If the ISP generates some string to advertise the user that it's time to enter the "ppp" command (like "now you can type ppp"), replace the null string "" with a final portion of this string.

PAP authentication

Many ISPs will not use a type-in authentication process like the above. When PAP authentication is used, the chat dialog must stop after the CONNECT string, in order to pppd start sending and receiving frames to proceed to the authentication. In this case, the options file must include some other clauses:

    lock
    crtscts
    defaultroute
    noauth

User information must be put on the /etc/ppp/pap-secrets file, much like the following example:

    # Secrets for authentication using PAP
    # client      server   secret        IP addresses
    foo             *     mysecret

A more complete chat script

Some desired features are absent from the example chat script above, in order to make it more readable. The one that follows includes advertising on modem responses that may be used to detect failures (for instance a busy line), warnigns useful to monitor the entire process, and display supression of authentication information:

    ABORT BUSY
    ABORT 'NO CARRIER'
    ABORT 'NO DIAL TONE'
    ABORT 'NO DIALTONE'
    SAY "Dialling your ISP...\n"
    "" ATZ OK ATM1L0 OK ATD1234567
    ECHO ON
    CONNECT ""
    ECHO OFF
    SAY "\nConnected, now logging in ...\n"
    ogin foo ssword mysecret
    SAY "Logged in OK"

Demand dialling

The pppd demand dialling feature is currently unsupported by uplink, but it's planned to be supported in the near future.

2.7 IP Masquerading

When you connect to your ISP, your computer receives an IP number and uses it to configure the ppp interface created by pppd. Then, from now till the connection is broken, every time you access a computer on the Internet (for instance a web server), this IP number is used to identify yourself and to route the information you requested back to you.

The other computers on your LAN did not receive an IP number from the ISP, and if they try to access a server on the Internet, they will identify themselves using the internal IP number that was chosen during the LAN tcpip configuration. That server will probably receive the request, but it will be unable to route back the information requested.

To solve this problem, all requests from the other computers on the LAN must achieve the Internet as if they were generated on the DCS, because only it has (at least for some time) an "official" IP number. When the information requested comes back to the DCS, it will need to be able to route it back to original client.

There are basically two ways to make the trick. You can use proxy servers or activate IP masqerading on the DCS. Both solutions can be used simultaneously. In order to activate IP masquerading on Linux, the kernel must have support for it (this is generally true for precompiled kernels from the major distributions). The package ipfwadm must be installed too. Then issue the following command:

    # ipfwadm -F -a accept -m -S 192.168.0.0/16

The network number 192.168.0.0 must be changed to the network number you're really using. The number 16 must be changed to the number of bits "1" in the binary representation of your network mask (for instance 8 if your mask is 255.255.0.0, and so on). If you add the command to your boot scripts, IP masquerading for packets generated on the LAN will be automatically configured on every boot.

In order to test if IP masquerading is working, make the link to the ISP up, and try to access some Internet server (for instance a web server or a ftp server) from some LAN machine other than the DCS.

3. Uplink Installation

Yet the configuration and test of all communication components will demand some reasonably effort, uplink installation is very simple, and will be described now in detail.

3.1 Uplink installation

Uplink installation is no more than customize its configuration file and copy it and the script to adequate directories. When fax services are desired, the print queues will need to be created too. Tests will require some work, because each service will need to be specifically tested. The steps are roughly the followings:

All these steps will be commented in detail along this documentation.

3.2 The spool

The spool is the place where uplink will maintain faxes and some other files. Currently the spool must be the directory /var/spool/lpd because it's hardcoded on the programs (this will change soon). Three other directories must be created:

    # mkdir /var/spool/lpd
    # chmod 755 /var/spool/lpd
    # cd /var/spool/lpd
    # mkdir old pages cache

The directory pages will contain the fax pages. The directory cache will be used when generating bitmaps for fax preview or some other files. The old directory will be discussed in the end of this section. Normally there will be only two files on /var/spool/uplfax: jobs and ddir.

[The jobs file]

The jobs file contains a database of submitted faxes. It has fixed-lenght records, on per line. Each record has 10 fields. The fields are space-separated to make easier to examine the file on a text editor. The fields are:

offset field size description
0 job 6 Job number. A 6-digit hexadecimal number, as 0002E9
6 1 blank separator
7 file 7 Basename of the files that contain the pages. Usually the job number plus a 'H' for high-resolution jobs or 'L' for low resolution jobs.
14 1 blank separator
15 pages 3 Number of pages, a 3-digit decimal number
18 1 blank separator
19 owner 20 Job owner
39 1 blank separator
40 sender 20 Sender. Currently the IP number of the sender
60 1 blank separator
61 status 1 Job status: S for sent, F for failed, C for cancelled, or a counter of the number of tries till now (one decimal digit)
62 1 blank separator
63 rcpt 80 The recipient number
143 1 blank separator
144 ctime 8 Creation time, a 8-digit hexadecimal number
152 1 blank separator
153 lttime 8 Time of last try, a 8-digit hexadecimal number
161 1 blank separator
162 key 40 Key. The key from the control/data files of the job submission
202 1 line feed

[The ddir file]

The ddir contains a very simple dialling directory. Each line is an entry. The lines may have variable sizes. The last field in each line is to be considered the recipient number. Example:

    Grandma 2345-6789
    Bill Gates 123-4567
    Joe's garage 34-5678

[Spool maintenance]

As time goes by, the spool will become more populated, so it's a good idea to remove old jobs in order to save disk space. The PURGE command moves to the old directory 7-day old fax pages, or as specified by its argument. The jobs file is split. The records corresponding to old jobs are appended to the jobs file located at the old directory (if this file does not exist, it's created. Once on the old directory, the fax pages can be compressed, for instance

    # zip -9m faxes.zip * -x jobs

Of course you can use any other tool. The compressed archive may be moved to another media or deleted, as desired.

3.3 Uplink configuration file

The uplink configuration file is a perl script executed during uplink startup. The beta version of uplink will not report syntax errors on this file, so be careful when editing it, and check by yourself if the syntax is correct:

    # perl uplink.cf

This script makes no more than initialize some variables that control uplink behaviour. The ultimate reference for these variables is the uplink.cf file itself.

Some of these variables specify the available ISPs. For each ISP, a nickname must be chosen, that will be used to refer that ISP through the ISP command. Unless you use qmail, the nicknames will also be also used to specify per-isp sendmail.cf files. Then a corresponding entry on %CHATSCRIPT or %DN must be defined. For instance, if the ISPs nicknames are "myisp" and "fast", the configuration file will need to refer things like

    $CHATSCRIPT{'myisp'} = '/etc/ppp/pppchat.myisp';
    $CHATSCRIPT{'fast'} = '/etc/ppp/pppchat.fast';

Or perhaps

    $CHATSCRIPT{'myisp'} = '/etc/ppp/pppchat.myisp';
    $DN{'fast'} = '1234567';

Note that for each ISP you'll create only the %CHATSCRIPT or only %DN entry, depending on if there is a chatscript available for that ISP, or only the dial number is informed. The chatscripts (if any) must be manually written. For all ISPs you'll normally write a chatscript, but if PAP authentication is used, it may suffice only to define the dial number. In this case, the script used will be

    "" ATZ OK ATDnumber CONNECT

When using PAP, the authentication info must be correctly put on the place that pppd will look for it, as explained earlier.

The faxmodem init string used for sending faxes may be very specific to your faxmodem. Follow the manufacturer's recommendations (if any). You'll find useful hints on the mgetty+sendfax documentation. Read also the "modem initialization section" on the efax man page.

The configuration file will be dinamically re-read every time a RECONFIG command is issued. The reconfig may interfere with running FETCH commands. A SIGHUP will have the same effect as RECONFIG, but may provoke other side-effects on running commands.

3.4 Command-line client

The command-line uplink client allows to issue individual commands, and may be used by at or cron jobs. Examples:

    $ uplcmd servername 2345 'send'
    $ uplcmd servername 2345 'fetch'

3.5 Text-based uplink client

Once started, uplink listen connections on TCP port 2345. The command interface was designed to allow control uplink through a telnet session. So just type:

    # telnet host 2345

Where host denotes the DCS. A bunch of commands are then available, please check the reference . To make sure that the configuration of all communication components is OK, you'll probably need to test most commands. Most of the warnings generated by those components will be forwarded to you by uplink, making easier to diagnose problems. For instance:

    $ telnet hal 2345
    Trying 192.168.0.1...
    Connected to hal.home.unet.
    Escape character is '^]'.
    103 hal.home.unet [192.168.0.1] joined us as client 0
    103 uplink v0.9e ready!
    UP
    103 UP request
    104 Jan 31 12:40:26 hal pppd[1457]: pppd 2.3.3 started by root, uid 0
    104 Dialling your ISP...
    104 ATDP61918262
    104 CARRIER 28800
    104 PROTOCOL: LAP-M
    104 CONNECT
    104 Connected, now logging in ...
    104 Logged in OK
    104 Jan 31 12:40:58 hal pppd[1457]: Serial connection established.
    104 Jan 31 12:40:59 hal pppd[1457]: Using interface ppp0
    104 Jan 31 12:40:59 hal pppd[1457]: Connect: ppp0 <--> /dev/ttyS0
    200 local IP is 200.245.169.143
    201 remote IP is 200.245.169.3

The messages generated by uplink are classified by numeric codes (103, 104, 200 above). A complete reference of these codes is available.

3.6 Win32 uplink client

Win32 support allows to control uplink and to submit faxes through samba. These operations are performed using a simple C application specially designed for that. In fact, the fax submission is performed through other applications, like word processors or web browsers, using theirs standard print features. The print job is addressed for a print queue managed by samba on the DCS. Then the lpd filter will move the fax to the fax spool. At this point, uplink will detect the job and will ask the user for the recipient(s) number(s). Then, the uplink app will be focused on the windows desktop, and the user will be invited to inform the recipient(s) number(s).

Currently the application menus and messages are presented in brazilian portuguese, but an english version is in the plans for the first public release. The menus and buttons allow to issue a limited portion of the commands available from the text interface, but offer graphical fax preview. A highway-style animation on the top right informs the user if there is or not a data connection to the ISP.

The installation of the win32 client is very easy. Just copy the executable file uplink.exe to the desired directory (for instance C:\UPLINK), together with the uplink.ini file provided in the distribution, any windows bitmap file black-and-white with resolution 216x269, and 5 animation frames (road?.bmp). Two such files are provided by the uplink distribution: penguin.bmp (a Linux penguin) and tiger.bmp (yes, the ghostscript tiger). This file must be renamed to uplink.bmp. So the installation process is:

    C:\DISTDIR\> MKDIR \iplink
    C:\DISTDIR\> COPY UPLINK.EXE C:\UPLINK
    C:\DISTDIR\> COPY SOME.BMP C:\UPLINK\UPLINK.BMP
    C:\DISTDIR\> COPY ROAD?.BMP C:\UPLINK\

The windows print queues will need to be created. This trivial operation must be done after the creation of the print queues on the DCS. By now, uplink offers no windows print drivers, so you'll need to obtain one from elsewhere. The print job must be submitted to the DCS in postscript format. The standard win95 driver for the HP5 printer is known to work fine with uplink. Before using this or other postscript commercial driver, one needs to check if this usage will not infringe its license terms.

4. The Email server

At this point, the DCS must be configure in order to work as smtp/pop/imap server to the LAN. The smtp server must deliver local email immediately, and must queue emails with external recipients. Both sendmail and qmail may be configured in order to offer this behaviour.

4.1 Configuring sendmail

The usual behaviour of sendmail includes two characteristics that are undesirable for a dialup server: DNS lookups are performed during initial SMTP steps, and queue processing is automatic. Both need to be disabled.

Basically you'll need a sendmail.cf file specially prepared. One such sendmail.cf is provided by the uplink package. It does not provoke DNS lookups, and disables queue processing by specifying that the major relay must not be connected because it is "expensive". It must be edited in order to specify the correct relay (the smtp server of your ISP).

Be aware that the provided sendmail.cf is derived from earlier sendmail distributions, and does not comply with recent features like those for span avoidance or usage of the virtual user table. As soon as we can, a more up-to-date sendmail.cf will be provided.

Once you have a sendmail.cf, put it on the right place (probably /etc), and change your boot scripts in order to sendmail be started without the -q switch. Now you're ready for internal email processing. All internal emails will be instantly delivered by sendmail, and those with external (Internet) recipients will be queued.

Most installations use more than one ISP. As the ISP smtp server is specified by the sendmail.cf file, you'll need one such file for each ISP. The naming scheme required by uplink is to put an .ISP extension on the sendmail.cf. For instance, if you use the ISPs "myisp" and "fast", create copies of the basic sendmail.cf:

    # cd /etc
    # cp sendmail.cf sendmail.cf.myisp
    # cp sendmail.cf sendmail.cf.fast

And edit the copies putting on the DR and CR clauses the name of each ISP smtp server (currently you'll need to make that even if only one ISP is defined!). An example of how to proccess the email queue is given on the section on testing the MTA.

4.2 Installation and Configuration of qmail

The qmail distribution is source-code only, so there are no binaries ready to run. The installation is not hard. Download the sources and follow the instructions (a good place to start is www.qmail.org ). You'll need to deal with some details, but if you're using qmail I suspect you're aware of them. Please install ucspi-tcp and serialmail too.

At this point qmail will hopefully be able to deliver local email. Emails to external (Internet) recipients will need to be redirected to an special user, say,

    # echo ":alias-ppp" > /var/qmail/control/virtualdomains
    # /var/qmail/bin/maildirmake ~alias/pppdir
    # echo "./pppdir/" > ~alias/.qmail-ppp-default

Now all non-local emails will be put on the same place until maildirsmt is invoked to deliver them to your ISP smtp server. An example of the invocation of maildirsmtp is given on the section on testing the MTA.

4.3 MTA test procedures

Basically one needs to send emails using the DCS as smtp server. A good way to make that is by hand, using a telnet client, because it'll be easier to diagnose problems like a broken IP connectivity, server inactive or client unauthorized (authorization may depend on the packet filters being used, on wrappers like tcpd, or on native MTA features).

But if you prefer not to issue manually the smtp commands (you'll not learn here how to make that), emails can also be sent by any true email client (see the next section for details on how to configure them). In any case, emails with local recipient(s), with external recipient(s), and with local and external recipients mixed must be sent to the DCS in order to test it.

Local recipients must receive immediately the emails sent, and emails with external recipients must be queued (even on the mixed case). In all cases, no delay must occur (other than a minimun one, say, two or three seconds, required for the client generate headers, convert file formats and transfer the whole thing to the DCS).

In order to check if the emails with external recipients are or not queued, use mailq for sendmail, or check the mailbox of the ppp alias for qmail, if configured as explained above. In order to check if local email was delivered or not, check directly the mailboxes on the filesystem, or try to fetch them emails using one email client (see the next section for details on how to configure it).

The queue processing will be performed by uplink by exec-ing a sendmail -q (when the MTA is sendmail) or a maildirsmtp (when the MTA is qmail). These commands may be manually issued (we strongly recommend you to make that, in order to confirm if it's everything working). To make that, connect to one ISP and execute one of the following:

    # sendmail -C/etc/sendmail.cf.isp -q

(please change isp by the name of the ISP you're currently connected to).

    # maildirsmtp ~alias/pppdir alias-ppp- smtpserver 'hostname'

(please change smtpserver by the ISP smtp server name, like smtp.foo.com).

The effect of that will be to transfer all queued emails to the ISP smtp server, that will deliver them to the final recipients. The last step is to check if the emails really arrived there...

Perhaps you're asking why the DCS MTA does not deliver the emails directly to the final recipients. The answer is that it's usually faster to transfer them first to the ISP smtp server (because it's nearer than the final recipient). The ISP smtp server will also deal with temporary failures on the final recipient mx host, scheduling the delivery for later, avoiding the need for many dials to send the email.

4.4 Configuring and testing email clients

Once your MTA (sendmail or qmail) is configured as described above, all email clients on the LAN will need to be configured to use the DCS as smtp server. You'll also want to configure it as POP/IMAP server.

This is just a matter of know how to configure each email client. Windows clients sometimes must be specifically configured to access the smtp/pop/imap through the LAN, and not through the modem, and sometimes it's not "intuitive" how to configure that.

Of course the DCS will need to have a working pop/imap server. If your email client cannot retrieve email from the DCS please check if a pop/imap server compatable with the MTA mailbox format is installed and active.

If someone intends to read or write email directly on the DCS, clients that don't rely on smtp or pop/imap (like Mail or others) may be used. Most clients that rely on smtp or pop/imap can also operate (when used on the DCS) without these protocols, for instance exec-ing sendmail directly or reading email directly from the filesystem.

4.5 Configuring fetchmail

A first example of a fetchmail configuration file is

    poll mail.myisp.com proto pop3
          user bozo with pass bozopass is bozo here forcecr
          user sales with pass salespass is joe here forcecr

The forcecr clause will force carriage returns (the MTA may require CRs, if unsure, please don't remove the forcecr). Other examples may be found on the fetchmailrc man page.

Every time you run fetchmail, it will read the configuration file (~/.fetchmailrc by default) and try to fetch the emails as specified:

    # fetchmail -a
This is just what uplink will do every time it receives a FETCH command. If the operation is successfull, the emails on the remote mailboxes will be put on local mailboxes for the LAN clients. Many servers and mailboxes may be specified in one configuration file.

More than one configuration file may be used. The FETCH command without arguments will refer always the .fetchmailrc file on the home directory of the uplink process owner (root). The mirroring facilities of uplink (that will be discussed later) are an easy way to deal with various (perhaps per-user) fetchmail configuration files. In this case, an argument must be specified to the FETCH command. This argument must be an object or group name as configured on the uplink.mc file.

4.6 What about uucp?

Of course uucp would be a nice solution, but the email support currently available on uplink is more general, and compatable with almost any ISP and virtual domain hosting services. When possible, an alternative configuration of uplink based on uucp will be available.

5. The Fax Server

The fax server will deliver fax jobs submitted from the LAN. It's possible to receive faxes if dialin mode is enabled, but currently uplink will not handle directly the received faxes (that is, uplink will not register these faxes on the fax database and operations like preview or print will not be available for them).

As a first step, it's important to make tests in order to make sure that your environment (hardware, operating system and line) allows reliable fax operation. If the fax delivery is not reliable, try to change (when possible) one piece at a time (line, faxmodem) in order to detect the source of the problems. The sendfax documentation contains many brand-specific hints.

In order to make tests you'll need to know the faxmode device name (say, /dev/cua2) and the the classes supported by your faxmodem (check its manual, or issue an AT+FCLASS=? command using any communication software). Once the delivery tests are OK, you'll be able to finish the fax server installation and configuration.

5.1 Testing efax

This section will tell you how uplink sends a fax using efax. Then, you will be able to make tests manually, in order to diagnose probles or to perform fine-tuning.

The commands below generate a high-resolution tiffg3 file from a (small) text source by efix, a companion of the efax package (if you're using version 0.8a of efax on a recent linux box, maybe you want to try the fixed binary included in the uplink distribution. That file is then delivered to 123456:

    $ efix doc.txt >doc.fax
    $ efax -d /dev/cua2 -o 1 -t 123456 doc.fax

If the input file is not small, there will be more than one output page, and you'll need to specify a list of files to efax. In this case use:

    $ efix -n "doc.%d" doc.txt
    $ efax -d /dev/cua2 -o 1 -t 123456 doc.001 doc.002 ...

Before reproducing this test, change the serial port device dev/cua2 and the fax class 1 as required. Change also, of course, the recipient number.

5.2 Testing sendfax

The sendfax support on the current uplink development version is broken. Please use efax instead, when possible.

5.3 Creating the DCS print queues

Fax jobs are generally submitted through standard lpd print queues. Because of this, print queues must be created on the DCS. Most platforms provide native tools to create and maintain print queues. If this is your case, use them. The directions below apply to those systems that use a printcap file.

Two queues must be created. One for high resolution (204x196 dpi) faxes and another for low resolution (204x98) faxes. The entries on printcap must look like these:

psfax-hi:\
        :sd=/var/spool/lpd/psfax-hi:\
        :mx#0:\
        :sh:\
        :lp=/dev/null:\
        :if=/usr/local/sbin/fp_psfax-hi:
psfax-lo:\
        :sd=/var/spool/lpd/psfax-lo:\
        :mx#0:\
        :sh:\
        :lp=/dev/null:\
        :if=/usr/local/sbin/fp_psfax-lo:

Currently the names of the queues must be psfax-hi and psfax-lo, and the name of the filters must be fp_psfax-hi and fp_psfax-lo. The other parameters may differ from the example. Note that the device is /dev/null, because the filter itself will move the job to the fax spool. The filters are links to the fillpipe program, part of the uplink distribution, so you'll proceed as follows:

    # cc -o fillpipe fillpipe.c
    # cp fillpipe /usr/local/sbin
    # cd /usr/local/sbin
    # chmod a+s fillpipe
    # ln -s fillpipe fp_psfax-hi
    # ln -s fillpipe fp_psfax-lo

Please be aware that the fillpipe binary will run with root privileges, because of the setuid above. You can avoid this if in your system the filter is executed by lpd with the required privileges to write on the fax spool.

5.4 Submitting fax jobs directly

The fax spool is pooled by uplink, that searches new fax jobs there. Each job is composed by at least two files, a control file and a data file (in some cases more than one data file may be present), linked by a common key that is part of the filename. The control file is that generated by the print spool, with fields P, N, J, etc (see lpd(8)). Two additional fields are supported: R, for remote fax number, and Q, for fax quality. The distribution provides examples for the cf file.

Currently the data file may be submitted in any one of three formats: text (iso), postscript or tiffg3. So to send a fax is just a matter of copy to the fax spool the control and data files. This operation is called direct submission of faxes. Of course this copy must be done carefully in order to preserve data integrity. The rules are:

  • The control file must be copied before the data file(s).
  • For text and postscript submissions, the data file is unique. It must be created by an atomic operation (mv). Text files must have a .txt "suffix". Postscript files must have a .ps "suffix".
  • Jobs submitted in tiffg3 format must have one data file per page, the pages must have the "suffix" .ddd. The first fax page must have number 001. The first page must be the last to be put on the spool, and this must be an atomic operation (mv).
  • The application must take care to avoid key duplication when submitting faxes directly.

Examples of direct submission:

    # copy cfdoc1.txt /var/spool/uplfax
    # copy dfdoc1.txt /var/spool/uplfax/dfdoc1.txt.tmp
    # cd /var/spool/uplfax
    # mv dfdoc1.txt.tmp dfdoc1.txt
    # copy cfdoc2.txt /var/spool/uplfax
    # copy dfdoc2.003 /var/spool/uplfax/dfdoc2.003
    # copy dfdoc2.002 /var/spool/uplfax/dfdoc2.002
    # copy dfdoc2.001 /var/spool/uplfax/dfdoc2.001.tmp
    # cd /var/spool/uplfax
    # mv dfdoc2.001.tmp dfdoc2.001

Direct submission is mostly useful to integrate uplink to your existing administrative software. So if you add to your system the ability of generate the control and data files as required by your needs, the fax delivery becomes a very simple task (just copy the files to the right place).

5.5 Submitting fax jobs through lpd

Of course the print server lpd may be used to generate the control and data files as required by uplink. In fact, uplink was designed in order to allow an easy integration with the print system. The print filter, in this case, will convert postscript to tiffg3, copy the control file (generated by the print subsistem) and the tiffg3 pages to the fax spool.

Note that when the control file is generated by the print subsystem, the R field that informs the fax recipient is absent. In this case, uplink will mark the fax as having unknown delivery information, and will try to ask this information to the client that submitted the job. Currently this requires two things: (1) the client IP number must be known and (2) the client must be running an uplink client with a TCP connection established with uplink itself.

This method creates a problem hard to deal with, to known, a truly multiuser computer cannot be used as a client, because all users share the same IP number. By now there is no solution for this problem other than restrict fax submission to those computers with monouser OSes, or to workstations with multiuser OSes but that in practice are used by only one user at a time.

5.6 Submitting jobs from windows

MS-Windows clients are able to submit fax jobs using the print facility provided by most windows applications. When samba exports the print queues, these jobs may be directed to samba, that will redirect them to lpd. The temporary file created by samba contains the original client hostname, so the field N of the control file may be used to deduce the client IP number.

So when a job is submitted from a windows application, uplink will be able to contact the uplink client running on that client, in order to ask the recipient number. At this point, the win32 client distributed as part of the uplink package, will gain focus and will display a message asking the user to enter the recipient number. The number informed will be sent to uplink through an FAXR command.

Two problems remain when using windows clients. The first one is that samba versions currently used for uplink development (1.9) truncate the client name to its prefix of size 6. So uplink will not be able to identify clients with long names unless their prefixes of size 6 are also registered on the LAN nameserver. The second problem is that multiuser NT machines (Citrix, or the NT terminal server) will not be able to act as uplink clients, as explained before.

5.7 How to test fax delivery without a telephone line

In some cases it's possible to test fax delivery without a telephone line. It's very useful, for instance when

  • you don't have a telephone line available for tests.
  • you don't have a remote recipient to receive the faxes.
  • fax delivery is unreliable and you need to make a large number of tests varying parameters (speed, size, class, capabilities string, modem, fax software, operating system, etc).
  • you want to discover if transmission failures are due to your equipment or to the telephone line.
  • You want use the fax machine as printer or scanner.
Of course you'll need a second faxmodem or a fax machine to act as the sender or recipient. The procedure described below will not work for all combinations of faxmodem or fax machines brands (don't ask me why). You'll need to manually control both sides.

Just connect the DCS faxmodem (the one that will be used for fax delivery) with the other faxmodem or with the fax machine, using a standard telephone cable (with RJ-11 connectors on both sides). You must use the "wall" (or "telco" or whatever name the manufacturer chose) connectors on both sides, and not the "phone" connectors, used to extend the line. Now try to adapt one of the following example for your environment:

[from Zoltrix v32 Rockwell-based (efax) to Sportster 33k (efax)]

Both modems are at /dev/ttyS2, on different machines. The test worked both for starting first the sender process or the recipient process. Sender process:

    # efax -o 1 -i "&D2&K6X3" -d /dev/ttyS2 -t 1 doc.fax

Where 'doc.fax' is a tiffg3 input file (see the section on testing efax ). Recipient process:

    # efax -o 0 -i "&D2&H3X3" -d /dev/ttyS2

[from Sportster 33k (sendfax) to Zoltrix v32 Rockwell-based (efax)]

Both modems are at /dev/ttyS2, on different machines. This test worked fine starting the sender process before the recipient process. The sendfax documentation contains important information on using USR modems for faxing. Sender process:

    # sendfax -l ttyS2 -m X3 1 doc.fax

Where doc.fax is a raw fax file (don't use a tiffg3 file). The recipient process is:

    # efax -o 1 -i "&D2&K6X3" -d /dev/ttyS2

[from Zoltrix v32 Rockwell-based (efax) to Samsung FX40 fax machine]

The modem is at /dev/ttyS2. This test worked fine pressing the fax machine START button before firing up the sender process:

    # efax -o 1 -i "&D2&K6X3" -d /dev/ttyS2 -t 1 doc.fax

[from Samsung FX40 fax machine to Zoltrix v32 Rockwell-based (efax)]

The modem is at /dev/ttyS2. This test worked fine starting the recipient process before pressing the fax machine START button. Recipient process:

    # efax -o 1 -i "&D2&K6X3" -d /dev/ttyS2

[using simulfax]

Finally, if you're a developer and want to debug or change uplink code, a fax delivery simulator is available. It's name is simulfax. Please configure it as the fax delivery agent. It'll not try to use the faxmodem device. It'll only wait a (small) random amount of seconds and return a random-generated answer about the delivery final status (success or failure).

6. Mirroring files and web pages from the Internet

The mirroring features have two major applications: (1) periodically refresh web pages (for instance news pages) on the local cache, making them available to the LAN clients, and (2) manage large downloads during off hours (for instance download a 30 megabyte archive along two nights).

6.1 Enabling wwwoffle

From the various web proxy servers currently available, wwwoffle is a very interesting choice for networks with a dialup connection to the Internet. It allows to browse the cached pages when disconnected, in a transparent way, as if you were connected, and provides a very nice administration interface. For details, check http://www.gedanken.demon.co.uk/wwwoffle/ .

In order to activate the uplink support for wwwoffle, you need to inform the machine:port specification required by wwoffle when a online of offline notification is performed. For instance:

    $WWWOFFLE_SRV = "192.168.0.1:8081";

Then uplink will notify wwwoffle every time the link becomes up or down. The mirroring facilities of uplink may also benefit from the features of wwwoffle, please see the example in the next section.

6.2 Specifying objects to mirror

The web pages and files to be mirrored are specified on the /etc/uplink.mc file. This file is a perl script executed by uplink during startup. Every time the status of some entry changes, uplink rewrites this file. Each 6 entries of the @FETCH list are a 6-field "object" specification. The commands FETCH/CHANGE/INVAL/DELETE may refer an object or a group of objects. The descriptions of the fields follow:

  • name: the name by which this object will be individually referred by the FETCH/CHANGE/INVAL/DELETE commands. An alphanumeric string ([a-zA-Z0-9]+).

  • grouplist: a comma-separated list of groups. Each group is an alphanumeric string ([a-zA-Z0-9]+). When the FETCH/CHANGE/INVAL/DELETE command refers an argument within this grouplist, this object will be affected by the command.

  • status: 'complete', 'incomplete', 'refresh' or 'ignore'. Every time you add an object, specify 'incomplete' or 'refresh'. The FETCH command will affect only objects with statuses 'incomplete' or 'refresh'. When the FETCH successfully completes the object fetch command, uplink changes the status 'incomplete' to 'complete' ('refresh' remains as is). The CHANGE command changes unconditionally the object status to a given one. The INVAL command changes the object status from 'complete' to 'incomplete'.

  • diagnostic: the return value of the mirror command that signifies "operation succesfully completed". If the command behaviour is unknown (perhaps undocummented), specify '?'

  • fcommand: the fetch command. This command is performed when the FETCH command is issued to uplink.

  • dcommand: the delete command. This command is performed when the DELETE command is issued to uplink.

Example:

    @FETCH = (
        'freshmeat',
        '',
        'incomplete',
        '?',
        'wwwoffle www.freshmeat.net -gSifs -p webproxy:8080',
        '',

        'bobmail',
        'mail',
        'refresh',
        '0',
        'fetchmail -a -f ~bob/.fetchmailrc',
        ''
    );

Note that the FETCH/INVAL/IGNORE/DELETE commands does not specify if the argument must be considered as an object name or as a group name. One same string may occur both as object name and group name, and one same string may be used as object name for more than one object. Each command will affect all objects to which the argument is its name or occurs within its grouplist.

6.3 Scheduling the mirror procedures

The uplink script itself does not provide schedule facilities, but rely on the OS for that. Unix-like systems have at and cron commands, that may be used to issue commands to uplink at given days or times, once or periodically. For instance, you can instruct cron to execute

    uplcmd host 2345 'fetch offhours'

Every night in order to make the DCS mirror the entries from the group offhours. If these include large downloads, the better solution is to issue this command every 30 or 60 minutes, in order to prevent yourself from modem hangups. The command

    uplcmd host 2345 'down'

Will stop fetching, and may be issued automatically by cron on morning.

7. Dialin support

The current strategy used by uplink dialin support is to fire up a preconfigured getty process every time the line becomes idle, and kill it when someone on the LAN requests the line for data or fax.

This method offers a simple way to use the line for incoming data, fax or voice calls, yet the input from the call (e.g. a fax or a voice message) will not be automatically handled by uplink.

Whether the system will handle or not each type of call (data, fax and voice), simultaneously or not, will depend on the getty capabilities. By now our examples include uugetty, for data-only, and vgetty, for data/fax/voice.

7.2 Enabling dialin support

In order to enable dialin, the $GETTY variable must contain a working getty command, and the $DIALIN variable must contain 1. The $DIALIN variable may be dinamically changed through the DIALIN command. The sections that follow show examples on how to configure $GETTY.

7.2 Configuring uugetty

For data-only incoming calls, uugetty is a good choice. The simplest configuration would be

    $GETTY = "uugetty -d uugetty.upl ttyS0 38400";

Where uugetty.upl is a configuration file put on the uugetty default directory for configuration files (this is platform dependent), and ttyS0 is the modem device. The contents for uugetty.upl could be

    INITLINE=ttyS0
    TIMEOUT=60
    INIT="" \d+++\dATH0\r OK\r\n AT\s&F\sE1\sX4\sS0=0\r OK\r\n
    WAITFOR=RING
    CONNECT="" ATA\r CONNECT\s\A
    DELAY=1

This configuration will make uugetty answer the call after the first ring (note that the answer command will be issued bu uugetty, and not automatically by the modem). Depending on your modem defaults, may be useful to customize the init string. Other commands you'll probably want to add are M0 for silently operation, and S7=<n> to avoid collect calls.

7.3 Configuring vgetty

Using vgetty it's possible to answer data, fax and voice calls. Hopefully, each type of call will be correctly recognized, and the modem and the computer will act as required. The default configuration will play a message, will try data and fax connections, and record a message from remote. An alternative is to write an answering script based on DTMF tones recognized by the modem.

Faxing will require a class-2 modem. Voice requires a voice modem. The minimal configuration could be

    $GETTY = "vgetty -n 3 ttyS2";

Where ttyS2 is the device, and 3 rings will be required before answer the call. You'll need also customize the vgetty configuration file. Please refer the vgetty docs. You'll find there information on the vgetty configuration file, and on vgetty behaviour when answering a call and detecting data, fax or voice calls. There is also documentation on how to write customized scripts. In the near future we'll try to put here some examples.

8. Miscellaneous

8.1 TODO list

  • A better sendmail.cf file.
  • Complete the implementation of the DELETE command.
  • A unix client that allows fax preview.
  • To make possible to send a voice message ("press the start button please") or a DTMF sequence before the fax.
  • Support for multiple lines (?).
  • Add examples on using fax delivery without a telephone line with windows native software.

8.2 Portability

To be able to run uplink, a platform must run at least the communication components desired (pppd, getty, etc). Most unix-like platforms run all components supported by uplink, so it'll not be hard to use them. Currently Linux is the development platform. The author uses uplink on Linux and FreeBSD boxes. Yet some of the communication components run on win32, the server was not tested till now on non-unix systems.

8.3 Notes on Security and Robustness

Very careful programming was performed in order to make uplink stable and secure. There are basically some details, however, that must be worked on:

  • If the system crashes during the initial steps of the processing of a directly-submitted fax, the fax may be ignored by uplink on the next cycle. The submitted files, however, will remain on the fax spool.
  • Up to now, the fax pages are not carefully protected nor regarding the files and directories permissions, nor regarding ownership checkings that would must be done by some commands (PREVIEW and PRINT).
  • Every client able to connect to the server will have full privileges (in the sense that it will be able to issue any uplink command), even those dangerous (like MAILRM).
  • Check the possibility of avoiding the need of root privileges both for uplink and fillpipe.
  • Add a log of suspicious or dangerous operations.

Hopefully, all these problems will be solved till the first public release of uplink.

8.4 Related Software

As we're not up-to-date with these nice softwares, it's better to check their homepages to confirm their current state:

  • diald is a dial-on-demand server. It creates a SLIP pseudo link, points the default route to it and listen for incoming packets, applying filter rules. When needed, fires up a command to make the link up. A very nice graphic interface is available to control the link.

  • masqdialer is more similar to uplink than diald. It allows clients on the LAN control the lines attached to the server for connections to the ISPs.

8.5 Reference of commands

The commands currently supported by uplink and theirs arguments follows. The command names may be issued in uppercase or lowercase. The command names may be abbreviated to any prefix that will identify it uniquely (e.g. "H BL" instead of "HELP BLOCK").

BINARY set binary preview and periodic status advertising
BLOCK asks whether the line is blocked
BLOCK 1 blocks line
BLOCK 0 unblocks line
The BLOCK command blocks the line both for incoming and outgoing calls
The BLOCK command does not terminate an active call
Issue DOWN after BLOCK to make sure that no outgoing call is active
BOTH perform SEND and FETCH (in this order)
CHANGE name st changes the named object status to st
CHANGE group st the same, for objects from this group
CLIENTS show list of connected clients
DELETE name exec the delete command of the named object
DELETE group the same, for objects from this group
The DELETE command is not implemented
DIALIN asks whether dialin mode is on or off
DIALIN 0 disable dialin mode
DIALIN 1 enable dialin mode
DOWN put the link down
Any running 'fetch' or 'send' commands will be killed
Queued fetches will not be killed
Will not terminate an incoming call
Will not stop a fax transmission in progress
FAXA id resend fax
FAXC id cancel fax
FAXF id forward fax
New recipient will be asked to original sender
FAXQ show all faxes
FAXQ a [a] show active fax jobs [from all]
FAXQ c [a] show cancelled fax jobs [from all]
FAXQ f [a] show failed fax jobs [from all]
FAXQ l [a] show all faxes [from all]
FAXQ q [a] show fax queue [from all]
FAXQ s [a] show sent fax jobs [from all]
FAXR id rcpt specify fax recipient
FAXSEL list dialling directory
FETCH fetch emails from default .fetchmailrc
FETCH name fetch named object
FETCH group fetch objects from this group
FETCHQ show fetch queue
HELP show list of commands
HELP topic show help on topic
IDLE show idle timeout to disconnect (in seconds)
IDLE n set idle timeout to disconnect (in seconds)
ISP show ISPs
ISP name select named ISP
INVAL name change the named object status from complete to incomplete
INVAL group the same, for objects from this group
MAILQ show mail queue
MAILRM key remove specified mail from queue
NETSTAT show network connections
PREVIEW n id pg preview n-reduced fax page pg from job id
PRINT id print fax
PURGE move 7-day old fax pages and db entries to 'old' directory
PURGE N the same, for N-day old
PURGE Ns the same, for N-second old
RECONFIG re-read uplink.cf and uplink.mc
This command may interfere with running FETCH commands
QUIT close connection
SEND process mail queue
STATUS show status
UP dial to the current ISP

8.6 Reference of messages

The messages generated by uplink are classified by type. Each type has a corresponding numeric code, that prefix the message as usual on TCP protocols. The set of commands and messages define informally an application-level TCP protocol. The numeric codes of the messages are:

    000 - unclassified

    100 - help messages
    101 - status messages
    102 - error messages
    103 - internal event messages
    104 - event messages from pppd/chat
    105 - event messages from fetchmail
    106 - event messages from smtpsend

    200 - local IP number
    201 - remote IP number
    202 - interface name
    203 - IDLE timeout
    204 - STATE
    205 - currrent ISP
    206 - link state
    207 - ISPs list
    208 - fax queue
    209 - faxsel output
    210 - fax page bitmap
    211 - fax successfully sent
    212 - fax failed
    213 - periodic status message
    214 - purge output
    215 - mailq output
    216 - fetchq output

    301 - server requests fax recipient
    302 - wakeup

8.7 Availability and Credits

The currently beta version of uplink is available for download and usage under the terms of the GNU GPL from ftp://ftp.ime.usp.br/pub/ueda/uplink/ .

Ricardo Ueda Karpischek wrote uplink. Adriano Nagelschmidt Rodrigues provided the necessary directions in order to correctly configure qmail. The development of uplink was originally suggested by Andre Wolff from Canuto Bookstore (www.canuto.com.br). Roberto Hirata, Fernando Rosendo, Marko Loparic and Adriano Nagelschmidt were originally involved with the work from which uplink resulted. William George Schauff contributed with many tests and suggestions. Of course nothing would be done without the efforts of so many people that writes free software, mainly those required to uplink work, but they're too much to list here.