Installation Manual for asterisk, FreePBX, iaxmodem, Postfix and HylaFax on openSUSE and WinPrintHylaFax on Windows lient

Preface
This is an installation manual for receiving and sending fax with HylaFax by fax-to-email and email-to fax on openSUSE and install manual for Win rintHylafax that you send email-to-fax from your Windows clients! This assumes that you have "steris# and dahdi installed! $ wrote it %pen&ox '()) $nstallation *anual for dahdi on openSUSE! +reate $", extension on Free ', read $nstallation *anual for Free ', on openSUSE!

Run asterisk as non-root user

$f asteris# run as non-root user it safer because $-ll change it! *a#e sure you .etc.init!d.asteris# stop and run "steris# as non-root!
.etc.init!d.asteris# stop /0 Shutting down asteris#1 %2

$t is safer to define a user called asteris# in group asteris# unless you want to ma#e more changes t o 3 files i!e! 4aptel!rules and .etc.init!d.asteris#
/ .usr.sbin.groupadd asteris# .usr.sbin.useradd -d .var.lib.asteris# -g asteris# asteris# /0 useradd1 warning1 the home directory already exists! /0 5ot copying any file from s#el directory into it!

*odify these directories owner user and group!

chown -6 asteris#1asteris# .var.lib.asteris# chown -6 asteris#1asteris# .var.log.asteris# chown -6 asteris#1asteris# .var.run.asteris# chown -6 asteris#1asteris# .var.spool.asteris# chown -6 asteris#1asteris# .usr.lib.asteris# // $f you are using 7aptel run the next line chown -6 asteris#1asteris# .dev.4ap // $f you are running 8"H8$ run the next line chown -6 asteris#1asteris# .dev.dahdi

*odify these directories file permissions.

chmod -6 u9rw,:g9r,:o9 .var.lib.asteris# chmod -6 u9rw,:g9r,:o9 .var.log.asteris# chmod -6 u9rw,:g9r,:o9 .var.run.asteris# chmod -6 u9rw,:g9r,:o9 .var.spool.asteris# chmod -6 u9rw,:g9r,:o9 .usr.lib.asteris# // $f you are using 7aptel run the next line chmod -6 u9rw,:g9r,:o9 .dev.4ap // $f you are using 8"H8$ run the next line chmod -6 u9rw,:g9r,:o9 .dev.dahdi chown -6 root1asteris# .etc.asteris# chmod -6 u9rw,:g9rw,:o9 .etc.asteris#

'ac#up .etc.steris#.asteris#!conf
cp .etc.asteris#.asteris#!conf .etc.asteris#.asteris#!conf!org

Edit .etc.asteris#.asteris#!conf! +hange the following line from1

/ astrundir 90 .var.run

to1
/ / astrundir 90 .var.run.asteris#

Edit .etc.init!d.asteris# and uncomment "ST;USE6 and "ST;<6%U ! +hande the following line from1
/ /"ST;USE69=asteris#= / /"ST;<6%U 9=asteris#=

to1
/ "ST;USE69=asteris#= / "ST;<6%U 9=asteris#=

"steris# needs to write to voicemail!conf for password change!

chmod g>w .etc.asteris#.voicemail!conf chmod g>w:>t .etc.asteris#

?et-s restart "steris# to ensure that both start up methods wor#!

.etc.init!d.asteris# restart

asteris# -U asteris# -< asteris#

$f that wor#s well: #illall asteris#: and then do asteris# -r to connect to "steris#-s command-line interface! $f all goes well with no errors: #illall asteris#: .etc.init!d.asteris# start: and then run asteris# -r! $f all goes well: congrats on ma#ing your "steris# phone system run as non-root! "steris# does not need =System "dministrator= powers in order to function! That-s it for "steris#! 5ow: let-s move in to iaxmodem!

$nstalling $",modem
$nstall iaxmodem from @ast rpm! A$f you use two modems then save it as tty$",): copy AcpB tty$",) to tty$",( and change the device to .dev.tty$",(: port to CDE(: and peername to iax-fax(!B +reate logfile directory in .ver.log. directory!1
/ m#dir .var.log.iaxmodem

*odify the configuration file .etc.iaxmodem.iaxmodem-cfg!tty$",)! This file must contain the following parameters1
device The device node to be created in .dev! This is the device Hylafax uses to connect to $",modem! @ou can choose any name you li#e: but we prefer to adhere to the convention and so choose a device name appropriate for a serial interface: tty$",)! owner This is the owner of the device Ain the form user1groupB! $t is best to use the same user and group under which Hylafax runs! port The port that $",modem listens on! "steris# uses CDFG to listen for $",3 connections: so you must choose something else: e!g! CDE)! refresh This sets how long $",modem waits between registrations with "steris#! $f this number is ): the modem does not register at all! server $ address of the server running "steris#! $f this is on the same machine as $",modem: use the localhost address (3E!)!)!(! peername The name under which $",modem registers with "steris#! secret The password used for "steris# registration! codec The codec used by $",modem! "llowed codecs are alaw: ulaw and slinear! +ompressed codecs are not appropriate for faxingH fax transmissions are themselves compressed and don-t tolerate further compressionH moreover: most compressed codecs are lossy and a fax transmission will not tolerate losses! This is one of the maIor reasons why faxing over &o$ remains problematic!

Using an appropriate editor Ae!g! viB we write the following configuration in the file .etc.iaxmodem.iaxmodem-cfg!tty$",)1
device owner mode port .dev.tty$",) uucp1uucp FF) CDE)

refresh server peername secret codec

J)) (3E!)!)!( G))( password)) ulaw

/it need that yuo haven-t iax registration failure on log

$",modem is now configured and can be started! The best way to do this is with @ast System Services A6unlevelB if you installed it from rpm! The device name tty$",) is the same device name as specified in .etc.iaxmodem! To receive faxes: we need a getty that listens for connections on the $",modem! This is accomplished through an additional entry in .etc.inittab! "dd it with echo =mo))13J1respawn1.usr.lib.fax.faxgetty tty$",)= 00 .etc.inittab!
mo))1JD1respawn1.usr.lib.fax.faxgetty tty$",)

+reate a log directory for $",modem with m#dir .var.log.iaxmodem. and the log files with touch .var.log.iaxmodem.tty$",) and touch .var.log.iaxmodem.iaxmodem!
/ m#dir .var.log.iaxmodem. / touch .var.log.iaxmodem.tty$",) / touch .var.log.iaxmodem.iaxmodem

To ma#e sure everything will start as expected at boot time: reboot the system with shutdown -r now!

$nstall ostfix
@ou need setup ostfix from voicemail file and edit .et !postfix!main!cf
relayhost 9 mail!t-online!hu smtp;sasl;password;maps 9 hash1.etc.postfix.sasl;password bro#en;sasl;auth;clients 9 yes smtpd;sasl;auth;enable 9 no smtp;always;send;ehlo 9 yes smtp;sasl;auth;enable 9 yes smtp;sasl;security;options 9 myhostname 9 host!domain /your host!domain name mydomain 9 domain /your domain name myorigin 9 domain!net /your domain FK85 masLuerade;domains 9 domain!net /your domain FK85 smtp;generic;maps 9 hash1.etc.postfix.generic

edit !et !postfix!sasl"passwd

mail!isp!net username1password /your username and passford of $S service

edit !et !postfix!#eneri

faxMhost!domain faxMhost!local faxMdomain!net faxMdomain!net /your domain F8K5 or $S domain FK85 /your domain F8K5 or $S domain FK85

edit !et !$osts

(G3!(FN!(!()) hoast!domain host /(3E!)!)!( hoast!domain host

Then run

postmap .etc.postfix.sasl;password postmap .etc.postfix.generic rcpostfix restart

Installing Hylafax
We-ll install Hylafax from @ast to simplify installation! 8ependencies are automatically resolved1 The next step is the configuration of the fax server! 8o this with faxsetup1
/ faxsetup O!!!P Update .var.spool.hylafax.status.any!info! HylaF", configuration parameters are1 O(P $nit script starts faxL1 O3P $nit script starts hfaxd OJP Start paging protocol1 "re these o# OyesPQ yes yes no

Simply press Enter after the following 3-J Luestions!

@ou have a HylaF", scheduler process running! faxL will be restarted shortly: as soon as some other wor# has been completed! +an $ terminate this faxL process AC)CNB OyesPQ Should $ restart the HylaF", server processes OyesPQ .etc.init!d.hylafax start 5ot starting HylaF", daemons since they are already running! O!!!P *odems are configured for use with HylaF", with the faxaddmodemANB comma nd! 8o you want to run faxaddmodem to configure a modem OyesPQ

We confirm restart of the server processes with yes and are as#ed if we want to install a modem! %ur $",modem is already set up so we can proceed and confirm again with yes! Specify the modem and confirm with Enter!
Serial port that modem is connected to OttyS)PQ tty$",) %#: time to setup a configuration file for the modem! The manual page configADB may be useful during this process! "lso be aware that at any time you can safely interrupt this procedure!

6eading scheduler config file .var.spool.hylafax.etc.config!

*any Luestions follow: but only a few of them are really important! This is where you set international dialing codes: the fax number: country and area code: and the +S$8 A+all Subscriber $8B which is printed on the top line of the fax page on the receiver-s end! +onfirm with yes!
5o existing configuration: let-s do this from scratch! +ountry code O(PQ CC "rea code OPQ ( hone number of fax modem O>(!GGG!DDD!(3(3PQ (3JCDFE ?ocal identification string Afor TS$.+$<B O=5othingSetup=PQ ?ong distance dialing prefix O(PQ ) $nternational dialing prefix O)((PQ )) 8ial string rules file Arelative to .var.spool.hylafaxB Oetc.dialrulesPQ Tracing during normal server operation O(PQ Tracing during send and receive sessions O((PQ rotection mode for received facsimile O)F))PQ rotection mode for session logs O)F))PQ rotection mode for tty$",) O)F))PQ 6ings to wait before answering O(PQ *odem spea#er volume OoffPQ +ommand line arguments to getty program O=-h Rl dx;Rs=PQ athname of TS$ access control list file Arelative to .var.spool.hylafax B O==PQ athname of +aller-$8 access control list file Arelative to .var.spool.h ylafaxB O==PQ Tag line font file Arelative to .var.spool.hylafaxB Oetc.lut6S(N!pcfPQ Tag line format string O=From RRlSRcS age RR of RRT=PQ Time before purging a stale UU+ loc# file AsecsB OJ)PQ Hold UU+ loc#file during inbound data calls O@esPQ Hold UU+ loc#file during inbound voice calls O@esPQ ercent good lines to accept during copy Luality chec#ing OGDPQ *ax consecutive bad lines to accept during copy Luality chec#ing ODPQ *ax number of pages to accept in a received facsimile O3DPQ Syslog facility name for ServerTracing messages OdaemonPQ Set U$8 to ) to manipulate +?%+"? O==PQ Use available priority Iob scheduling mechanism O==PQ

" confirmation page follows where you can double-chec# your entries1
The non-default server configuration parameters are1 +ountry+ode1 "rea+ode1 F",5umber1 ?ong8istance refix1 8ialString6ules1 ( (3JCDFE ) etc.dialrules CC

$nternational refix1 ))

SessionTracing1 6ings'efore"nswer1 Spea#er&olume1 <etty"rgs1 ?ocal$dentifier1 Tag?ineFont1 Tag?ineFormat1 *ax6ecv ages1 "re these o# OyesPQ

(( ( off =-h Rl dx;Rs= =5othingSetup= etc.lut6S(N!pcf =From RRlSRcS age RR of RRT= 3D

"nswering yes brings us to modem detection1

5ow we are going to probe the tty port to figure out the type of modem that is attached! This ta#es a few seconds: so be patient! 5ote that if you do not have the modem cabled to the port: or the modem is turned off: this may hang AIust go and cable up the modem or turn it on: or whateverB! robing for best speed to tal# to modem1 JNC)) %2! "bout fax classes1 The difference between fax classes has to do with how HylaF", interacts with the modem and the fax protocol features that are used when sending or receiving faxes! %ne class isn-t inherently better than anotherH however: one probably will suit a user-s needs better than others! +lass ( relies on HylaF", to perform the bul# of the fax protocol! +lass 3 relies on the modem to perform the bul# of the fax protocol! +lass 3!) is similar to +lass 3 but may include more features! +lass (!) is similar to +lass ( but may add &!JC-fax capability! +lass 3!( is similar to +lass 3!) but adds &!JC-fax capability! HylaF", generally will have more features when using +lass (.(!) than when using most modems- +lass 3 or +lass 3!) implementations! <enerally any problems encountered in +lass (.(!) can be resolved by modifications to HylaF",: but usually any problems encountered in +lass 3.3!).3!( will reLuire the modem manufacturer to resolve it! $f you-re unsure and your modem supports it: use +lass (! This modem loo#s to have support for +lass ( and (!)! How should it be configured O(PQ Hmm: this loo#s li#e a +lass ( modem! roduct code A"T$)B is =spandsp=! %ther information A"T$JB is =www!soft-switch!org=! 8TE-8+E flow control scheme OdefaultPQ

*odem manufacturer is =spandsp=! *odem model is =$",modem=! Using prototype configuration file iaxmodem!!! The modem configuration parameters are1 *odem6eset+mds1 "re these o# OyesPQ ="TH(Tn"T>&+$89(=

The modem was detected and we are as#ed if it is a +lass ( modem: and we confirm this because it is exactly what we want! The default reset commands are also acceptable! +onfirm with yes!
"nswer the first Luestion $n the next dialog with no: since we don-t need to configure any further modems! The second Luestion is confirmed with by pressing Enter: which starts the fax server!
+reating new configuration file .var.spool.hylafax.etc.config!tty$",)!!! +reating fifo .var.spool.hylafax.F$F%!tty$",) for faxgetty!!! done! 8one setting up the modem configuration! O!!!P 8o you want to run faxaddmodem to configure another modem OyesPQ no O!!!P Should $ run faxmodem for each configured modem OyesPQ .usr.sbin.faxmodem tty$",) 8one verifying system setup! .var.spool.hylafax

Hylfax is now configured for sending faxes! 1) Receiving faxes IMP R!"#!! $f you not use Free ', need edit configs below: but if you use Free ', then you need setup it on Free ', *anager <U$! %ur fax solution still has to be integrated into "steris#! To do this: we configure the $",modem as an $",3 peer by adding a section to .etc.asteris#.iax!conf1
OgeneralP bindport 9 CDFG bindaddr 9 )!)!)!) disallow9all allow9ulaw allow9alaw OG))(P type9friend

secret9password)) transfer9no Hhost9(3E!)!)!( port9CDE) host9dynamic context9from-internal reLuirecallto#en9no disallow9all allow9alaw HIitterbuffer9no Lualify9yes deny9)!)!)!).)!)!)!) dial9$",3.G))( mailbox9G))(Mdevice callerid9device UG))(0 setvar96E"?+"??E6$85U*9G))( permit9(3E!)!)!(.3DD!3DD!3DD!) Hany other modems you have in .etc.iaxmodem. will go here!

<lobal settings are defined in the general section! $n this example we are binding the standard $",3 port of CDFG! The bindaddr defines the $ address Aand thereby the interfaceB on which the $",3 channel driver listens for connectionsH in this case: it is set to listen on all interfaces! The $",modem is set to type friend: which allows both incoming and outgoing connections! The secretand port parameters match those in the $",modem configuration we did above: and context defines the entry context for outgoing connections! Enter iax3 show peers in the "steris# console to see our new $",modem1
/asteris# -rvvvvvvvv V+?$0 iax3 show peers 5ame.Username Host tus iaxmodem onitored ( iax3 peers O) online: ) offline: ( unmonitoredP V+?$0exit (3E!)!)!( A8B 3DD!3DD!3DD!3DD CDE) Unm *as# ort Sta

$) %ending faxes IMP R!"#!! $f you not use Free ', need edit configs below: but if you use Free ', then you need setup it on Free ', *anager <U$! The next obvious step is configuring our system to send faxes! Here: too: we need a context Athis time it isOfax-outPB in extensions!conf! $f $",modem wants to send a fax: it will automatically land in this context! $f the faxes are to go out our hypothetical S$ connection (3JCDF: the entry in extensions!conf will loo# li#e this1
Ofax-outP exten 90 ;,!:(:8ialAS$ .(3JCDF.WXE,TE5YB

We can test sending of faxes with sendfax -n -d Ufaxnumber0 Ufile!txt01

/ sendfax -n -d F)CDDDEGEE .etc.issue!net

$f you finished then you can send and receive faxes via "steris# using Hylafax! The Hylafax website http1..www!hylafax!org has numerous examples and how-tos that will help you integrate your Hylafax installation with your existing office intrastructure effectively! &) %ending received faxes as e-mail The following steps illustrate how we can configure Hylafax to transmit incoming faxes to a predefined e-mail address!The recipient will receive the fax as an e-mail attachment! To do this: the configuration file .var.spool.fax.bin.Fax8ispatch must contain the following parameters1
%'#(! The destination e-mail address for incoming faxes! )I*'!+P' The format of the attachment! $n addition to pdf: tiff ATagged $mage File FormatB and ps A ostscriptZB are also acceptable options!

*odify these parameters to1

SE58T%9usernameMdomain!net F$?ET@ E9pdf /sending to e-mail address

"fter the file has been saved: you must restart the fax server with .etc.init!d.hylafax restart!
/ rchylafax restart Shutting down service HylaF", Starting service HylaF", done done

We can test e-mail transmission by sending ourselves a fax with sendfax -n -d Ufaxnumber0 Ufile!txt0
/ sendfax -n -d 3E3(DEC .etc.host

The attachment will be a 8F file! 5ow you can not only send and receive faxes: but received faxes are also received as e-mail attachments! ,) "dd faxuser %nce you-ve completed that part of the setup we have to create some users that they can use Win rintHylafax! type =faxadduser -a -adminpass. -p -userpass. -u -uid. -username.= -a adminpass is a password you ma#e up that allows the user to login with admin privelages to the fax server: set it to whatever you li#e -p userpass is the normal user password for the person logging in -u uid is a / !!! F%6 E,"* ?E1 -u () HE6E $S " S"* ?E USE6 TH"T $ SET U =faxadduser -a adminpass -p userpass -u 100 username= !!! That will create a user called =username= with the user id of =())= and a

password of =userpass= with admin privelages accessible via =adminpass= 8oes this ma#e senseQ

/inPrintHylafax
I copied here manual 0ecause the installation is very simple and manual is very useful1 Winprint HylaF", is a Windows print monitor designed to send its output directly to a HylaF", Server! %nce installed: you can print to a HylaF", Server from any application: and it will pop up a simple dialog box: allowing you to enter the destination F", number! $t-s not intended to be fancy or all encompassing: Iust a Luic# and easy way to send F",es from any Windows application $t can be downloaded here! To go to the sourceforge pages for this software to comment: report bugs: or get source code: clic# here! $t is pac#aged in the form of a Windows $nstaller: which installs the reLuired sets of !8?? files and registers the monitor with the system! This adds support for a new type of port to your system: called a =Win rint HylaF", ort!= %nce you-ve successfully installed the files: setup is straightforward: but it has a number of steps! First: you-ll want to create an appropriate ostScript printer using the ="dd rinter= button! @ou want to select a =?ocal printer:= but since it-s not a physical printer: unchec# the ="utomatically detect and install my lug and lay printer= box!

5ext: you-ll be as#ed what port to use! Select the radio button =create a new port type!= $f the installation went well: you should see =Winprint Hylafax= as one of the options!

The drop list might scroll: so it may not be obvious that it-s at the bottom of the list! A$f it doesn-t appear on the list at all: something went wrong with your installation!B

5ext: a box will pop up for you to name the port! The name doesn-t actually matter: but naming it HF",(1 will help to identify it!

5ext: select the printer type! Experience has shown that the "pple ?aserWriter (3.FC) S is a good choice: and $ recommend it! *ost any other ostScript printer will probably wor#!

%f course: name it whatever you want: preferably something that says: =hey: this is going to a F", machine!=

8o not share the printer! This is rather silly anyway: since you can locally install Winprint HylaF", on any system that needs it: and it communicates directly with the HylaF", server! Since it pops up the dialog box as#ing where to send the F", Iob locally: this would be ugly: at best! "lso: don-t print a test page: since you-re not done configuring the printer yet! 6ight-clic# on the printer to call up its properties: and select the = orts= tab! ?ocate the port you Iust created!

ress the =+onfigure ort= button to configure the connection to your HylaF", server!

*ost people who have problems are going to have problems because their HylaF", server won-t let them connect! 'rea# out your HylaF", server documentation: and ma#e sure that you have set up the correct permissions: which can be as simple as putting the $ address of your client into .var.spool.fax.etc.hosts!hfaxd! @ou may not need the username -or- password: in which case: you

can leave password blan#: but the username is always reLuired: even if it isn-t authenticated! %#ay: now you-re ready to print a test Iob! When you send anything to this printer: a dialog box will appear1

The F", number is completely unedited and unverified! $t relies on HylaF",-s dialing rules to ma#e sense of it! "s you would expect: the HylaF", server will send an e-mail confirming delivery Aor failure to do soB to the specified e-mail address!

!est environment
%S1 openSUSE ((!J xNF;FC 2ernel version1 3!F!JC!N-)!3-xen "steris# version1 "steris#-(!F!3!() 8ahdi version1 dahdi-linux-complete-3!J!)!(>3!J!) ?ibpri version1 libpri-(!C!((!C ostfix version1 postfix-3!E!(-3!F!( HylaFax version1hylafax-F!)!C-C!J!3 iaxmodem version1 iaxmodem-(!3!) Hardware%pen&ox '())