1HYLAFAX-CLIENT(1) General Commands Manual HYLAFAX-CLIENT(1)
2
6 HylaFAX-client - introduction to HylaFAX client applications and usage
7
9 sendfax [options] [files...]
10 sendpage [options] [message...]
11 faxstat [options]
12 faxrm [options]
13 faxalter [options] jobid...
14 fax2ps [options] [files...]
15
17 HylaFAX is a telecommunication system for UNIX® systems. Among the
18 features of HylaFAX are:
19 · HylaFAX runs as a network service; this means a modem may be effec‐
21 tively shared by a large number of users.
22 · HylaFAX can be configured to work with a wide variety of modems on a
24 wide variety of systems.
25 · Access to the system can be restricted by the administrator to
27 selected hosts and/or users.
28 · Transmission requests may be processed immediately (default) or
30 queued for processing at a later time, in the manner of the at(1)
31 command.
32 · Remote facsimile machines may be polled to retrieve publicly avail‐
34 able documents.
35 · POSTSCRIPT®, PDF, and TIFF Class F documents are passed directly to
37 the fax server for transmission; the system attempts to convert
38 other file formats to either POSTSCRIPT or TIFF through the use of
39 an extensible file typing and conversion facility. In normal opera‐
40 tion ASCII-text, troff(1) output, and Silicon Graphics images are
41 automatically converted. Additional file formats can be added; see
42 typerules(5F).
43 · The faxcover(1) program can be automatically invoked to create a
45 cover page for each facsimile, using information deduced by the
46 sendfax command. Alternatively, users may supply their own cover
47 pages using their preferred tools.
48 · Facsimile are normally imaged in a system-default page size (usually
50 letter-size pages, 8.5" by 11", for sites in North America). Alter‐
51 nate page sizes can be specified with a -s option to all HylaFAX
52 programs. Well known page sizes include: ISO A3, ISO A4, ISO A5,
53 ISO A6, ISO B4, North American Letter, American Legal, American
54 Ledger, American Executive, Japanese Letter, and Japanese Legal.
55 Note that it may not be permissible to image into the full page
56 area; the guaranteed reproducible area for a page is typically
57 smaller. Also, note that while arbitrary page sizes can be speci‐
58 fied, only a limited number of page dimensions are supported by the
59 facsimile protocol. Thus if an odd-size facsimile is submitted for
60 transmission it may not be possible to determine if it can be sent
61 until the fax server establishes communication with the remote fac‐
62 simile machine.
63 · Facsimile can be sent at low resolution (98 lines/inch) or medium
65 resolution (196 lines/inch)—often called fine mode. Documents with
66 mixed resolution pages are handled correctly.
67 · Users are notified by electronic mail if a job can not be transmit‐
69 ted. It is also possible to receive notification by mail when a job
70 has been completed successfully and each time that the job is
71 requeued for retransmission. Any untransmitted documents are
72 returned to the sender by electronic mail in a form suitable for re-
73 submission.
74 · Support is provided for broadcasting facsimile. The HylaFAX server
76 software optimizes preparation of broadcast documents and the client
77 applications support the notion of a job group which permits a group
78 of jobs to be manipulated together.
79 · Support is provided for transmitting alpha-numeric messages to pager
81 devices or GSM mobiles using the Simple Network Paging Protocol
82 (SNPP) and the IXO or UCP protocol (for message delivery).
83 The HylaFAX software is divided into two packages: software used on
85 client machines and software used on machines where one or more modems
86 reside. Client software includes:
87 · sendfax, a program to submit outgoing facsimile;
89 · sendpage, a program to submit alpha-numeric messages to SNPP
91 servers;
92 · faxstat, a program obtain status information about HylaFAX servers;
94 · faxrm, a program to remove jobs and documents;
96 · faxalter, a program to change parameters of queued jobs; and
98 · fax2ps, a program that converts facsimile documents to POSTSCRIPT so
100 that they may be viewed with a POSTSCRIPT previewer or printed on a
101 POSTSCRIPT printer (this program is actually part of the companion
102 TIFF distribution that is used by HylaFAX).
103 Many systems also support submission of outgoing facsimile by elec‐
105 tronic mail and/or graphical interfaces to the sendfax program. Such
106 facilities are site-dependent; consult local documentation for more
107 information.
108
110 To use the HylaFAX client software on your machine you need to either
111 load the appropriate software on your machine, or you need to locate a
112 machine that already has the client software installed and setup sym‐
113 bolic links to the appropriate directories. If you choose the latter,
114 then beware that you need links to three directories: the directory
115 where client applications reside, /usr/bin, the directory where the
116 client application database files reside, /etc/hylafax, and the direc‐
117 tory where document conversion programs reside, /usr/sbin (the last two
118 directories may be the same on your system).
119 Once the software is setup on your machine you need to locate a host
121 that has a facsimile server that you can use. The host, and possibly
122 the modem on the host, should be defined in your environment in the
123 FAXSERVER variable. For example, for csh users,
124 setenv FAXSERVER flake.asd
126 or for ksh or sh users,
128 FAXSERVER=flake.asd; export FAXSERVER
130 If there are multiple modems on your server then you may be assigned to
132 use a specific modem. For example, if you are to use the modem
133 attached to the ttym2 port on the server machine, then the FAXSERVER
134 variable should be setup as
135 FAXSERVER=ttym2@flake.asd; export FAXSERVER
137 (Note: the SNPPSERVER environment variable is used instead of FAXSERVER
139 by the sendpage program; consult sendpage(8C) for more information.)
140 Note also, that before you can submit outgoing facsimile jobs the
142 administrator for the facsimile server may need to register your iden‐
143 tity in an access control list. You will encounter the message ``530
144 User %s access denied.'' if access to your server is controlled and
145 you are not properly registered or you may be prompted for a password
146 and then denied service with ``530 Login incorrect.''.
147
149 A dial string specifies how to dial the telephone in order to reach a
150 destination facsimile machine. HylaFAX permits arbitrary strings to be
151 passed to the facsimile server so that users can specify credit card
152 information, PBX routing information, etc. Alphabetic characters are
153 automatically mapped to their numeric key equivalents (e.g. ``1800Got‐
154 Milk'' becomes ``18004686455''). Other characters can be included for
155 readability; anything that must be stripped will be removed by the
156 server before the dialing string is passed to the fax modem. Private
157 information such as credit card access codes are withheld from status
158 messages and publicly accessible log files (with proper configuration).
159 Facsimile servers also automatically insert any leading dialing prefix‐
160 ing strings that are required to place outgoing phone calls; e.g. dial‐
161 ing ``9'' to get an outside line. Additionally, if a phone number is
162 fully specified with the international direct dialing digits (IDDD),
163 then any prefixing long distance or international dialing codes that
164 are required to place the call will be inserted in the dial string by
165 the server. For example, ``+31.77.594.131'' is a phone number in the
166 Netherlands; it would be converted to ``0113177594131'' if the call is
167 placed in the United States. The number ``+14159657824'' is a phone
168 number in California; if this number is called from within the 415 area
169 code in the United States, then the server would automatically convert
170 this to ``9657824'' because in the San Francisco Bay Area, local phone
171 calls must not include the area code and long distance prefixing code.
172 The general rule in crafting dial strings is to specify exactly what
174 you would dial on your telephone; and, in addition, the actual phone
175 number can be specified in a location-independent manner by using the
176 IDD syntax of ``+country-code local-part''.
177
179 The sendfax program can automatically generate a cover page for each
180 outgoing facsimile. Such cover pages are actually created by the fax‐
181 cover(1) program by using information that is deduced by sendfax and
182 information that is supplied on the command line invocation of sendfax.
183 Users may also request that sendfax not supply a cover page and then
184 provide their own cover page as part of the data that is to be trans‐
185 mitted.
186 Automatically-generated cover pages may include the following informa‐
188 tion:
189 · the sender's name, affiliation, geographic location, fax number, and
191 voice telephone number;
192 · the recipient's name, affiliation, geographic location, fax number,
194 and voice telephone number;
195 · text explaining what this fax is ``regarding'';
197 · text commentary;
199 · the local date and time that the job was submitted;
201 · the number of pages to be transmitted.
203 Certain of this information is currently obtained from a user's per‐
205 sonal facsimile database file; ~/.faxdb. Note that this file is depre‐
206 cated; it is described here only because it is still supported for com‐
207 patibility with older versions of the software.
208 The .faxdb file is an ASCII file with entries of the form
210 keyword : value
212 where keyword includes:
214 Name a name associated with destination fax machine;
216 Company a company name;
218 Location in-company locational information, e.g. a build‐
220 ing#;
221 FAX-Number phone number of fax machine;
223 Voice-Number voice telephone number.
225 Data is free format. Whitespace (blank, tab, newline) can be freely
227 interspersed with tokens. If tokens include whitespace, they must be
228 enclosed in quote marks (``"''). The ``#'' character introduces a com‐
229 ment—everything to the end of the line is discarded.
230 Entries are collected into aggregate records by enclosing them in
232 ``[]''. Records can be nested to create a hierarchy that that supports
233 the inheritance of information—unspecified information is inherited
234 from parent aggregate records.
235 For example, a sample file might be:
237 [ Company: "Silicon Graphics, Inc."
238 Location: "Mountain View, California"
239 [ Name: "Sam Leffler" FAX-Number: +1.415.965.7824 ]
240 ]
241 which could be extended to include another person at Silicon Graphics
243 with the following:
244 [ Company: "Silicon Graphics, Inc."
245 Location: "Mountain View, California"
246 [ Name: "Sam Leffler" FAX-Number: +1.415.965.7824 ]
247 [ Name: "Paul Haeberli" FAX-Number: +1.415.965.7824 ]
248 ]
249 Experience indicates that the hierarchical nature of this database for‐
251 mat makes it difficult to maintain with automated mechanisms. As a
252 result it is being replaced by other, more straightforward databases
253 that are managed by programs that front-end the sendfax program.
254
256 HylaFAX client applications can be tailored on a per-user and per-site
257 basis through configuration files. Per-site controls are placed in the
258 file /etc/hylafax/hyla.conf, while per-user controls go in ~/.hylarc.
259 In addition a few programs that have many parameters that are specific
260 to their operation support an additional configuration file; these
261 files are identified in their manual pages.
262 Configuration files have a simple format and are entirely ASCII. A
264 configuration parameter is of the form
265 tag: value
266 where a tag identifies a parameter and a value is either a string, num‐
267 ber, or boolean value. Comments are introduced by the ``#'' character
268 and extend to the end of the line. String values start at the first
269 non-blank character after the ``:'' and continue to the first non-
270 whitespace character or, if whitespace is to be included, may be
271 enclosed in quote marks (``"''). String values enclosed in quote marks
272 may also use the standard C programming conventions for specifying
273 escape codes; e.g. ``\n'' for a newline character and ``\xxx'' for an
274 octal value. Numeric values are specified according to the C program‐
275 ming conventions (leading ``0x'' for hex, leading ``0'' for octal, oth‐
276 erwise decimal). Boolean values are case insensitive. For a true
277 value, either ``Yes'' or ``On'' should be used. For a false value, use
278 ``No'' or ``Off''.
279
281 Incoming facsimile are received by facsimile servers and deposited in a
282 receive queue directory on the server machine. Depending on the
283 server's configuration, files in this directory may or may not be read‐
284 able by normal users. The faxstat program can be used to view the con‐
285 tents of the receive queue directory:
286 hyla% faxstat -r
287 HylaFAX scheduler on hyla.chez.sgi.com: Running
288 Modem ttyf2 (+1 510 999-0123): Running and idle
289 Protect Page Owner Sender/TSI Recvd@ Filename
291 -rw-r-- 9 fax 1 510 5268781 05Jan96 fax00005.tif
292 -rw-r-- 8 fax 1 510 5268781 07Jan96 fax00009.tif
293 -rw-r-- 2 fax 1 510 5268781 07Jan96 fax00010.tif
294 -rw-r-- 3 fax +14159657824 08Jan96 fax00011.tif
295 -rw-r-- 2 fax +14159657824 08Jan96 fax00012.tif
296 Consult the faxstat manual page for a more detailed description of this
298 information.
299 Received facsimile are stored as TIFF Class F files. These files are
301 Bi-level images that are encoded using the CCITT T.4 or CCITT T.6
302 encoding algorithms. The fax2ps(1) program can be used to view and
303 print these files. A file can be viewed by converting it to POSTSCRIPT
304 and then viewing it with a suitable POSTSCRIPT previewing program, such
305 as xpsview(1) (Adobe's Display POSTSCRIPT-based viewer), ghostview(1)
306 (a public domain previewer), or image viewer programs such as view‐
307 fax(1) (public domain), faxview(1) (another public domain TIFF viewer
308 program), xv(1) (shareware and/or public domain), or xtiff(1) (a pro‐
309 gram included in the public domain TIFF software distribution). Con‐
310 sult your local resources to figure out what tools are available for
311 viewing and printing received facsimile.
312
314 HylaFAX client applications communicate with servers using either a
315 special-purpose communications protocol that is modeled after the
316 Internet File Transfer Protocol (FTP) or, when submitting alpha-numeric
317 pages, the Simple Network Paging Protocol (SNPP), specified in RFC
318 1861. All client programs support a -v option that can be used to
319 observe the protocol message exchanges. In some situations it may be
320 more effective to communicate directly with a HylaFAX server using the
321 client-server protocol. This can be accomplished with an FTP or Telnet
322 client application; though an FTP client is recommended because it
323 implements the protocol needed to obtain server status information.
324 For information on the server-side support provided with HylaFAX con‐
325 sult hfaxd(8C). For documentation on the client-server fax protocol
326 consult RFC XXXX (to be filled in).
327
329 This section gives several examples of command line usage; consult the
330 manual pages for the individual commands for information on the options
331 and program operation.
332 The following command queues the file zall.ps for transmission to John
334 Doe at the number (123)456-7890 using fine mode; the server will
335 attempt to send it at 4:30 A.M.:
336 sendfax -a "0430" -m -d "John Doe@1.123.456.7890" zall.ps
337 (the leading ``1.'' is supplied to dial area code ``123'' in the United
338 States.)
339 The following command generates a one-page facsimile that is just a
341 cover page:
342 faxcover -t "John Doe" -n "(123)456-7890"
343 -c "Sorry John, I forgot the meeting..." |
344 sendfax -n -d "(123)456-7890"
345 (note that the line was broken into several lines solely for presenta‐
346 tion.)
347 The following command displays the status of the facsimile server and
349 any jobs queued for transmission:
350 faxstat -s
351 The following command displays the status of the facsimile server and
353 any documents waiting in the receive queue on the server machine:
354 faxstat -r
355 The following command shows how to use an FTP client program to commu‐
357 nicate directly with a HylaFAX server:
358 hyla% ftp localhost hylafax
359 Connected to localhost.
360 220 hyla.chez.sgi.com server (HylaFAX (tm) Version 4.0beta005) ready.
361 Name (localhost:sam):
362 230 User sam logged in.
363 Remote system type is UNIX.
364 Using binary mode to transfer files.
365 ftp> dir sendq
366 200 PORT command successful.
367 150 Opening new data connection for "sendq".
368 208 126 S sam 5268781 0:3 1:12 16:54 No local dialtone
369 226 Transfer complete.
370 ftp> quote jkill 208
371 200 Job 208 killed.
372 ftp> dir doneq
373 200 PORT command successful.
374 150 Opening new data connection for "doneq".
375 208 126 D sam 5268781 0:3 1:12 No local dialtone
376 226 Transfer complete.
377 ftp> quote jdele 208
378 200 Job 208 deleted; current job: (default).
379 ftp> dir docq
380 200 PORT command successful.
381 150 Opening new data connection for "docq".
382 -rw---- 1 sam 11093 Jan 21 16:48 doc9.ps
383 226 Transfer complete.
384 ftp> dele docq/doc9.ps
385 250 DELE command successful.
386 ftp> dir recvq
387 200 PORT command successful.
388 150 Opening new data connection for "recvq".
389 -rw-r-- 4 fax 1 510 5268781 30Sep95 faxAAAa006uh
390 -rw-r-- 9 fax +14159657824 11Nov95 faxAAAa006nC
391 -rw---- 25 fax +14159657824 Fri08PM fax00016.tif
392 226 Transfer complete.
393 ftp> quit
394 221 Goodbye.
395 The following command shows how to use a Telnet client program to com‐
397 municate directly with an SNPP server:
398 hyla% telnet melange.esd 444
399 Trying 192.111.25.40...
400 Connected to melange.esd.sgi.com.
401 Escape character is '^]'.
402 220 melange.esd.sgi.com SNPP server (HylaFAX (tm) Version 4.0beta010) ready.
403 login sam
404 230 User sam logged in.
405 help
406 214 The following commands are recognized (* =>'s unimplemented).
407 214 2WAY* ALER* DATA HOLD LOGI MSTA* PING RTYP* STAT
408 214 ABOR CALL* EXPT* KTAG* MCRE* NOQU* QUIT SEND SUBJ
409 214 ACKR* COVE* HELP LEVE MESS PAGE RESE SITE
410 250 Direct comments to FaxMaster@melange.esd.sgi.com.
411 page 5551212
412 250 Pager ID accepted; provider: 1800SkyTel pin: 5551212 jobid: 276.
413 send
414 250 Message processing completed.
415 quit
416 221 Goodbye.
417 Connection closed by foreign host.
418
420 /usr/bin/sendfax for sending facsimile
421 /usr/bin/sendpage for sending alpha-numeric pages
422 /usr/bin/fax2ps for converting facsimile to POSTSCRIPT
423 /usr/bin/faxalter for altering queued jobs
424 /usr/bin/faxcover for generating cover sheets
425 /usr/bin/faxmail for converting email to POSTSCRIPT
426 /usr/bin/faxrm for removing queued jobs
427 /usr/bin/faxstat for facsimile server status
428 /usr/sbin/sgi2fax SGI image file converter
429 /usr/sbin/textfmt ASCII text converter
430 /etc/hylafax/typerules file type and conversion rules
431 /etc/hylafax/pagesizes page size database
432 /etc/hylafax/faxcover.ps prototype cover page
433 /etc/hylafax/dialrules optional client dialstring rules
434 /var/spool/hylafax/tmp/sndfaxXXXXXXtemporary files
435
437 at(1), fax2ps(1), faxalter(1), faxcover(1), faxmail(1), faxrm(1), faxs‐
438 tat(1), sgi2fax(1), faxq(8C), viewfax(1), hylafax-server(5F), dial‐
439 rules(5F), pagesizes(5F), typerules(5F), services(4)
440 May 8, 1996 HYLAFAX-CLIENT(1)