1JOBCONTROL(8C) JOBCONTROL(8C)
2
6 jobcontrols - per-job controls for HylaFAX servers
7
9 The HylaFAX configuration parameter JobControlCmd specifies the script
10 that is used to apply per-job controls on job characteristics such as
11 the time-of-day to place a call.
12 The controls program is passed the respective job ID number as the
14 first and only argument.
15 The controls program should produce a simple line-based ASCII output
17 containing a series of records of the form:
18 param: value
19 which is parsed the same manner as all HylaFAX config files. Parameter
20 values are parsed exactly as specified in hylafax-config(5F); i.e. val‐
21 ues with embedded whitespace may be enclosed in quote marks (``"'').
22 All output on a line following a ``#'' character is ignored.
24 The output order is important. The last parameter value in the output
26 overrides any previous values in the output. Otherwise a default value
27 is used from the faxq configuration file.
28 The following parameters may be output on a per-job basis; consult
30 hylafax-config(5F) for a description of each parameter (except Modem,
31 Priority, and RejectNotice which are described below).
32 Tag Type Default Description
33 MaxConcurrentCalls integer 1 max concurrent jobs to process for a destination
34 MaxDials integer unlimited max phone calls to make to transmit a job
35 MaxSendPages integer unlimited max pages to permit in a send
36 MaxTries integer 3 max attempts to transmit a job
37 Modem string Any ModemGroup to use for destination
38 Notify string - notification override for job
39 PageSize string - page size to use for job
40 Priority integer - priority to use for job
41 Proxy string - proxy server to which the job should be delivered
42 ProxyUser string - authentication username for the proxy server
43 ProxyPass string - authentication password for the proxy server
44 ProxyMailbox string - E-Mail address for job notification
45 ProxyNotification string none notification request
46 ProxyJobTag string see below jobtag for proxy job
47 ProxyLogMode octal 0600 protection to use for logs retrieved from proxy server
48 ProxyTaglineFormat string - impose tagline format for proxy job
49 ProxyTries integer -1 number of tries proxy should attempt
50 ProxyTSI string - impose TSI for proxy job
51 ProxyDials integer -1 number of dials proxy should attempt
52 ProxyReconnects integer 5 number of reconnections to proxy for any job submisison
53 RejectNotice string - rejection notice for transmit job
54 RewriteFaxname string - replace faxname in job request with this
55 RewriteFaxnumber string - replace faxnumber in job request with this
56 TimeOfDay string Any default time-of-day restrictions
57 VRes integer - Vertical resolution
58 UseXVRes integer - Usage of extended resolutions
59 UseColor integer - Usage of color
60 UseSSLFax integer - Usage of SSL Fax
61 The Modem parameter controls which ModemGroup is used in sending faxes
63 to the destination. If the user assigns a ModemGroup for a job where
64 there are no common modems between that ModemGroup and the ModemGroup
65 assigned here by JobControlCmd, then the JobControlCmd value of Modem
66 is overridden by the user's ModemGroup. Likewise, if the user assigns
67 a ModemGroup for a specific job where some, but not all, of the modems
68 are included in this ModemGroup matching a destination, then the value
69 of Modem is overridden by the inclusive set of modems found in both.
70 The Notify parameter allows an override of whatever notification
72 request the client requested in the job. Options are ``none'', ``when
73 requeued'', ``when done'', and ``when done+requeued''.
74 The PageSize parameter controls the page size for the job. This over‐
76 rides any page size requested by the submitter. Page sizes are defined
77 in the pagesizes(5F) database.
78 The Priority parameter controls the priority to assign to the job.
80 This overrides any priority requested by the submitter.
81 The Proxy parameter controls to which host the job should be delivered
83 for transmission. This should be a hostname or IP address and may
84 include the modem group name when formatted as the host option for
85 sendfax(1). The proxy server should have login access permitted for
86 the originating server without a password if ProxyUser and ProxyPass
87 are not also provided. Caution: actions such as job removal and job
88 modification (such as those done by faxrm(1) or faxalter(1)) will not
89 currently propagate to the proxy and is a matter for future develop‐
90 ment. Therefore, such actions should be made on the proxy server
91 directly.
92 The ProxyMailbox and ProxyNotification identify the e-mail address and
94 the notification mechanism for the proxied job. (This does not change
95 the e-mail address or the notification mechanism for the originating
96 job.)
97 The ProxyJobTag sets the jobtag for the job on the proxy server. By
99 default this is the jobid for the originating job.
100 The ProxyLogMode parameter specifies the file mode protection that
102 should be used for the logs that are able to be retrieved from the
103 proxy server. (In order to retrieve logs the proxy server must permit
104 it.)
105 The ProxyTaglineFormat sets the tagline format for the job on the proxy
107 server. By default this is whatever was specified by the client.
108 The ProxyTries and ProxyDials parameters specify the number of respec‐
110 tive attempts that the proxy server should make. The default is -1,
111 and any value less than 1 indicates that the proxy server should be
112 delegated all remaining attempts.
113 The ProxyTSI sets the TSI for the job on the proxy server. By default
115 this is whatever was specified by the client.
116 The ProxyReconnects parameter specifies the number of reconnections
118 that should be made to the proxy server in the event that the network
119 connection is lost. Attempts are made no sooner than 60 seconds apart,
120 so to tolerate a network outage of 30 minutes ProxyReconnects should be
121 set to ``30'' or higher.
122 The RejectNotice parameter controls whether or not to reject jobs to
124 the destination. Jobs that are rejected are done so without placing a
125 phone call and the associated message is returned to the job submitter.
126 This facility can be used to disallow calling sensitive phone numbers;
127 for example
128 RejectNotice: "Calls to emergency numbers are not permitted"
129 The RewriteFaxname and RewriteFaxnumber parameters allow the ``fax‐
131 name'' and ``faxnumber'' parameters in the job request file to be
132 replaced and rewritten with the given values.
133 The VRes parameter controls the vertical resolution. Possible values
135 are 98 (normal resolution, equivalent to sendfax -l option) and 196
136 (fine resolution, equivalent to sendfax -m option).
137 The UseColor parameter is used to enable or disable the usage of color
139 as supported by the receiver. Possible values are 1 (enable color
140 usage, equivalent to sendfax -O usecolor:yes option) and 0 (disable
141 color usage). This parameter may be used in conjunction with
142 DesiredDF: 6 in order to abort fax transmission if the receiver does
143 not support color facsimile.
144 The UseSSLFax parameter is used to enable or disable the usage of SSL
146 Fax as supported by the receiver. Possible values are 1 (enable) and 0
147 (disable).
148 The UseXVRes parameter is used to enable or disable the usage of
150 extended resolutions supported by the receiver. Possible values are 1
151 (enable extended resolutions usage, equivalent to sendfax -G option)
152 and 0 (disable extended resolutions usage). This parameter supersedes
153 the usage of VRes.
154 In addition to the above parameters, any other parameters that are
156 specified are automatically accumulated and passed to programs invoked
157 by faxq, such as faxsend and pagesend. (Note that in a batched-jobs
158 instance that these parameters will apply to all jobs in the batch.)
159 This is a convenient mechanism for defining configuration parameters
160 for all modems without having to modify each modem-specific configura‐
161 tion file. For example,
162 SessionTracing: 0x4f
163 This mechanism also makes it easy to control transmit-related parame‐
165 ters according to the destination phone number. For example, to dis‐
166 able use of ECM and restrict the transmit speed when placing interna‐
167 tional phone calls one might use:
168 DesiredBR: 3
169 DesiredEC: 0
170 DesiredDF: 1
171
173 Change (overlap) MaxDials parameter to 3 for all outgoing calls.
174 1. Create file bin/jobcontrol with the following content:
176 #!/bin/sh
177 echo "MaxDials:
178 exit 0
179 2. Ensure that bin/jobcontrol is marked as executable:
181 chmod +x bin/jobcontrol
182 3. Add parameter JobControlCmd to hylafax-config(5F); (etc/config)
184 file:
185 JobControlCmd: bin/jobcontrol
186 The controls program will likely need to refer to the sendq file corre‐
188 sponding to the job in order to obtain information such as the number
189 being dialed, the job owner, or the number of send attempts. For this
190 purpose the parseQfile function has been placed in bin/common-functions
191 to assist in this. For example:
192 #!/bin/sh
194 . etc/setup.cache
195 . bin/common-functions
196 QFILE=sendq/q$1
197 SetupPrivateTmp
198 parseQfile
199 case "$number-$owner-$tottries" in
200 5551212-lee-3) echo "Class1ECMSupport: no";;
201 *-sam-*) echo "LocalIdentifier: +1.800.555.1212";;
202 911-*) echo "RejectNotice: \"Calls to 911 are not permitted\"";;
203 esac
204 exit 0
205
208 JobControlCmd is run each time the job moves into the run-queue
209 ("READY" state), and all output is effective on each instance. If the
210 administrator wishes to vary output based on the attempt sequence, then
211 the q-file values should be consulted in the process. Furthermore,
212 blind usage of options such as Priority could be confusing as it would
213 essentially prevent a job from increasing or decreasing in job priority
214 as usually expected after call attempts.
215
217 faxq(8C), hylafax-config(5F), re_format(7).
218 Mar 27, 2006 JOBCONTROL(8C)