jobcontrols - per-job controls for HylaFAX servers
The HylaFAX configuration parameter JobControlCmd specifies the script
that is used to apply per-job controls on job characteristics such as
the time-of-day to place a call.
The controls program is passed the respective job ID number as the
first and only argument.
The controls program should produce a simple line-based ASCII output
containing a series of records of the form:
which is parsed the same manner as all HylaFAX config files. Parameter
values are parsed exactly as specified in hylafax-config(5F); i.e. val‐
ues with embedded whitespace may be enclosed in quote marks (``"'').
All output on a line following a ``#'' character is ignored.
The output order is important. The last parameter value in the output
overrides any previous values in the output. Otherwise a default value
is used from the faxq configuration file.
The following parameters may be output on a per-job basis; consult
hylafax-config(5F) for a description of each parameter (except Modem,
Priority, and RejectNotice which are described below).
Tag Type Default Description
MaxConcurrentCalls integer 1 max concurrent jobs to process for a destination
MaxDials integer unlimited max phone calls to make to transmit a job
MaxSendPages integer unlimited max pages to permit in a send
MaxTries integer 3 max attempts to transmit a job
Modem string Any ModemGroup to use for destination
Notify string - notification override for job
PageSize string - page size to use for job
Priority integer - priority to use for job
Proxy string - proxy server to which the job should be delivered
ProxyUser string - authentication username for the proxy server
ProxyPass string - authentication password for the proxy server
ProxyMailbox string - E-Mail address for job notification
ProxyNotification string none notification request
ProxyJobTag string see below jobtag for proxy job
ProxyLogMode octal 0600 protection to use for logs retrieved from proxy server
ProxyTaglineFormat string - impose tagline format for proxy job
ProxyTries integer -1 number of tries proxy should attempt
ProxyTSI string - impose TSI for proxy job
ProxyDials integer -1 number of dials proxy should attempt
ProxyReconnects integer 5 number of reconnections to proxy for any job submisison
RejectNotice string - rejection notice for transmit job
RewriteFaxname string - replace faxname in job request with this
RewriteFaxnumber string - replace faxnumber in job request with this
TimeOfDay string Any default time-of-day restrictions
VRes integer - Vertical resolution
UseXVRes integer - Usage of extended resolutions
UseColor integer - Usage of color
UseSSLFax integer - Usage of SSL Fax
The Modem parameter controls which ModemGroup is used in sending faxes
to the destination. If the user assigns a ModemGroup for a job where
there are no common modems between that ModemGroup and the ModemGroup
assigned here by JobControlCmd, then the JobControlCmd value of Modem
is overridden by the user's ModemGroup. Likewise, if the user assigns
a ModemGroup for a specific job where some, but not all, of the modems
are included in this ModemGroup matching a destination, then the value
of Modem is overridden by the inclusive set of modems found in both.
The Notify parameter allows an override of whatever notification
request the client requested in the job. Options are ``none'', ``when
requeued'', ``when done'', and ``when done+requeued''.
The PageSize parameter controls the page size for the job. This over‐
rides any page size requested by the submitter. Page sizes are defined
in the pagesizes(5F) database.
The Priority parameter controls the priority to assign to the job.
This overrides any priority requested by the submitter.
The Proxy parameter controls to which host the job should be delivered
for transmission. This should be a hostname or IP address and may
include the modem group name when formatted as the host option for
sendfax(1). The proxy server should have login access permitted for
the originating server without a password if ProxyUser and ProxyPass
are not also provided. Caution: actions such as job removal and job
modification (such as those done by faxrm(1) or faxalter(1)) will not
currently propagate to the proxy and is a matter for future develop‐
ment. Therefore, such actions should be made on the proxy server
The ProxyMailbox and ProxyNotification identify the e-mail address and
the notification mechanism for the proxied job. (This does not change
the e-mail address or the notification mechanism for the originating
The ProxyJobTag sets the jobtag for the job on the proxy server. By
default this is the jobid for the originating job.
The ProxyLogMode parameter specifies the file mode protection that
should be used for the logs that are able to be retrieved from the
proxy server. (In order to retrieve logs the proxy server must permit
The ProxyTaglineFormat sets the tagline format for the job on the proxy
server. By default this is whatever was specified by the client.
The ProxyTries and ProxyDials parameters specify the number of respec‐
tive attempts that the proxy server should make. The default is -1,
and any value less than 1 indicates that the proxy server should be
delegated all remaining attempts.
The ProxyTSI sets the TSI for the job on the proxy server. By default
this is whatever was specified by the client.
The ProxyReconnects parameter specifies the number of reconnections
that should be made to the proxy server in the event that the network
connection is lost. Attempts are made no sooner than 60 seconds apart,
so to tolerate a network outage of 30 minutes ProxyReconnects should be
set to ``30'' or higher.
The RejectNotice parameter controls whether or not to reject jobs to
the destination. Jobs that are rejected are done so without placing a
phone call and the associated message is returned to the job submitter.
This facility can be used to disallow calling sensitive phone numbers;
RejectNotice: "Calls to emergency numbers are not permitted"
The RewriteFaxname and RewriteFaxnumber parameters allow the ``fax‐
name'' and ``faxnumber'' parameters in the job request file to be
replaced and rewritten with the given values.
The VRes parameter controls the vertical resolution. Possible values
are 98 (normal resolution, equivalent to sendfax -l option) and 196
(fine resolution, equivalent to sendfax -m option).
The UseColor parameter is used to enable or disable the usage of color
as supported by the receiver. Possible values are 1 (enable color
usage, equivalent to sendfax -O usecolor:yes option) and 0 (disable
color usage). This parameter may be used in conjunction with
DesiredDF: 6 in order to abort fax transmission if the receiver does
not support color facsimile.
The UseSSLFax parameter is used to enable or disable the usage of SSL
Fax as supported by the receiver. Possible values are 1 (enable) and 0
The UseXVRes parameter is used to enable or disable the usage of
extended resolutions supported by the receiver. Possible values are 1
(enable extended resolutions usage, equivalent to sendfax -G option)
and 0 (disable extended resolutions usage). This parameter supersedes
the usage of VRes.
In addition to the above parameters, any other parameters that are
specified are automatically accumulated and passed to programs invoked
by faxq, such as faxsend and pagesend. (Note that in a batched-jobs
instance that these parameters will apply to all jobs in the batch.)
This is a convenient mechanism for defining configuration parameters
for all modems without having to modify each modem-specific configura‐
tion file. For example,
This mechanism also makes it easy to control transmit-related parame‐
ters according to the destination phone number. For example, to dis‐
able use of ECM and restrict the transmit speed when placing interna‐
tional phone calls one might use:
Change (overlap) MaxDials parameter to 3 for all outgoing calls.
1. Create file bin/jobcontrol with the following content:
2. Ensure that bin/jobcontrol is marked as executable:
chmod +x bin/jobcontrol
3. Add parameter JobControlCmd to hylafax-config(5F); (etc/config)
The controls program will likely need to refer to the sendq file corre‐
sponding to the job in order to obtain information such as the number
being dialed, the job owner, or the number of send attempts. For this
purpose the parseQfile function has been placed in bin/common-functions
to assist in this. For example:
case "$number-$owner-$tottries" in
5551212-lee-3) echo "Class1ECMSupport: no";;
*-sam-*) echo "LocalIdentifier: +1.800.555.1212";;
911-*) echo "RejectNotice: \"Calls to 911 are not permitted\"";;
JobControlCmd is run each time the job moves into the run-queue
("READY" state), and all output is effective on each instance. If the
administrator wishes to vary output based on the attempt sequence, then
the q-file values should be consulted in the process. Furthermore,
blind usage of options such as Priority could be confusing as it would
essentially prevent a job from increasing or decreasing in job priority
as usually expected after call attempts.
faxq(8C), hylafax-config(5F), re_format(7).
Mar 27, 2006 JOBCONTROL(8C)