Distributed Processing

Distributed Processing mode

callas pdfToolbox Server/CLI can be used in distributed processing mode in which all jobs are distributed over the network to as many "satellites" as being present and results are send back to the originator. Therefore pdfToolbox Server/CLI may be started in different modes:

  • "Dispatcher" must to be present exactly one time in the network. This node controls which jobs are to be processed by which machines: the "satellites".
  • "Satellite" receives jobs from the clients or directly from the dispatcher (if the dispatcher is run with hotfolders), processes them and sends them back to the clients.
  • "Client" asks the dispatcher for satellites and after receiving the next satellite it sends jobs to the satellites and receives the results.
  • "Monitor" monitors the dispatcher and displays the current situation.

All of these modules can run on the same or on different machines. There needs to be exactly one dispatcher and at least one satellite. In order to submit jobs at least one client is required.

Distributed processing is supported for Windows, MacOS, Linux, SunSolaris and SunIntel. It is not available on AIX.

Starting a Dispatcher

--dispatcher [--port=<port number>]


--dispatcher [--port=1200]

Port is the port number on which the dispatcher can be called over the network. This port is set to 1200 as default.

Starting a Dispatcher using the ServerUI

There is also the possibility to start a server as a dispatcher on Windows and MacOS using the user interface. Also hotfolder-processing can be set up here. In this mode, the dispatcher will also distribute jobs which are send by other clients.

Starting a Satellite

--satellite --endpoint=<Dispatcher IP
number>[:<dispatcher port]> [--port=<port number>]
[--connections=<number of concurrent connections]


--satellite --endpoint= --port=1201

In order to process jobs at least one Satellite is required.
Endpoint is the IP number and the port of the Dispatcher. Default is 1200,
but it can be changed at the start of the Dispatcher (see above).
Port is the port that the Satellite is using in order to communicate with
the Clients. The port of the Satellite is 1201 as default and can be defined
optionally to another one port at the startup.
It is highly recommended to use separate port numbers for the communication
between Satellite and Dispatcher than for Satellite and Client.

Starting a Satellite using the ServerUI

There is also the possibility to start a server as a Satellite on Windows and
MacOS using the user interface. In this mode, the Satellite will not process
any hotfolder jobs on the computer.
A Satellite will always use the number of CPUs on the respective machine
as the number of concurrent connections/processes. To limit this number,
the Satellite has to be started by CLI with the --connections parameter.
The number of connections should not exceed the number of CPUs, as this
might reduce the performance per process and could result in some system
stability problems.

Assign more than one Dispatcher to a Satellite
In order to connect a Satellite with more than 1 Dispatcher it is possible to
define more than one endpoint. Please refer the to the chapter "Fallback
for Dispatcher".

Distribute a process using a Client

The client is called using any regular pdfToolbox command line command.
In order to distribute the call over the network the command line parameters
--dist and --endpoint are added. The client will then first ask the dispatcher to receive a satellite connection and then send the command to the satellite and wait until the result is sent back from the satellite.

pdfToolbox --dist --endpoint=<dispatcher IP
number>[:<dispatcher port>] <any regular pdfToolbox call>


pdfToolbox --dist --endpoint=
<anyProfile.kfpx> <myPDF.pdf>
pdfToolbox --dist --endpoint=
--redistill <myPDF.pdf>

Set type of satellite

As some kinds of jobs shall only be processed on a defined type of Satellite, it is possible to start a Satellite with one or more types set.

Every CLI call can also be amended with one or more typification of allowed types of Satellites the job shall be processed by.

Set typification for Satellite:

pdfToolbox --satellite --endpoint=<dispatcher
IP number> --satellite_type=<type> [--satellite_

for example:

pdfToolbox --satellite --endpoint=
pdfToolbox --satellite --endpoint=
--satellite_type=A --satellite_type=B

Set typification for Client:

pdfToolbox --dist --endpoint=<dispatcher IP number>
--satellite_type=<type> [--satellite_type=<type>] <any
regular pdfToolbox call>

for example:

pdfToolbox --dist --endpoint= --satellite_
type=A <any regular pdfToolbox call>

Implementation details:

• If a Satellite has been started with a typification, only Client calls with the same type set will be send to this satellite.

• If a Client call contains a number of typifications, all typifications must match with those set for a satellite.

• If a Client call has no typfication set, it can be processe on all satellites, even they have been started with a typfication.

• The <type>-string has to be alpha-numeric and is case sensitive.

Avoid local processing

As a fallback, processing can be performed locally if either the action can not be distributed, a Satellite can not be assigned within a timeframe or if no Dispatcher is available.

This type of local processing might be not desired for several reasons.

To avoid such local processing, the Client call can be amended as well as the start of a Dispatcher (if run as a server with hotfolders) with the option


Example for Client:
pdfToolbox --dist --endpoint=<dispatcher IP number>
--nolocal <any regular pdfToolbox call>

Example for Dispatcher:
pdfToolbox --dispatcher --nolocal

Fallback for Dispatcher

In some workflow systems, a fallback for a Dispatcher might be required to ensure production stability.

To cover this, a number of Dispatcher can be set up, which will run individually.

One or multiple Dispatcher can be assigned to a Satellite.

Define multiple Dispatcher to a Satellite

Connects a satellite to two (or more) Dispatcher.

pdfToolbox --satellite --endpoint=<dispatcher 1 IP>
[--endpoint=<dispatcher 2 IP> [--endpoint=<dispatcher

Set multiple Dispatcher in a Client call

Distributes a Client call via two (or more) Dispatcher. First reachable Dispatcher with free satellite will process the job.

pdfToolbox --dist --endpoint=<dispatcher 1 IP>
--endpoint=<dispatcher 2 IP> [--endpoint=<dispatcher
IP>] <any regular pdfToolbox call>

Define a timeout for processing

In some workflow systems, long running processes might not be allowed and shall be cancelled if a give timeframe is reached.

Due to the flexibility of distributed processing, a variety of timeouts for the individual parts can be set:

  • for the Client call
  • for the Satellite
  • for the Dispatcher

Timeout for processing on a Satellite

When defining a timeout for the Client call, the execution will be cancelled after the given period.

When defining a timeout when starting a Satellite, all jobs processed by this Satellite will be cancelled after the given period.

If both are defined, the shorter timeframe will be used.

Example for Client:

pdfToolbox --dist --endpoint=<dispatcher IP> --timeout_
satellite=<seconds> <any regular pdfToolbox call>

Example for Satellite:

pdfToolbox --satellite --endpoint=<dispatcher IP>

Timeout for local processing of Dispatcher or Client
A processing timeout (if no satellite is available or if the type of job can not be distributed) for the fallback to local processing on the Client or the Dispacher
(when used as a server for hotfolders) can also be defined.
If both are defined, the shorter timeframe will be used.

Example for Client:

pdfToolbox --dist --endpoint=<dispatcher IP>
--timeout=<seconds> <any regular pdfToolbox call>

Example for Dispatcher:

pdfToolbox --dispatcher --timeout=<seconds>

Timeout for Dispatcher to search for Satellites
Additionally, also a timeout for the Dispatcher can be set, which will define
the timeframe in which is searched for Satellites.
This can be set individually for every Client call:

Example for Client:

pdfToolbox --dist --endpoint=<dispatcher IP> --timeout_
dispatcher=<seconds> <any regular pdfToolbox call>

When running the Dispatcher in hotfolder-mode, the setting can be
defined when starting the Dispatcher (will have effect on all distributed
files from hotfolders then):

Example for Dispatcher:

pdfToolbox --dispatcher --timeout_dispatcher=<seconds>

If a timeout for satellites or dispatcher is set and the --nolocal option has
been defined, it will not be tried to process the job locally. Processing will
end up in an error.
Setting --timeout... or --nolocal parameters in the "Additional CLI parameter"
area of the Server UI is not supported at the moment.

Using the CLI-Monitor

pdfToolbox --monitor --endpoint=<dispatcher
IP>:<dispatcher port> [--endpoint=<dispatcher
IP>:<dispatcher port>]


--monitor --endpoint=

Monitor is optional and mirrors the command line output of the dispatcher to another computer. Endpoint is the IP number and the port of the dispatcher.

When using more than one Dispatcher, also multiple Dispatcher IPs can be entered and observed.


  1. Clients sends a request for Satellite to Dispatcher
  2. Dispatcher assigns a Satellite and send the address to the Client
  3. Client send the job to the Satellite
  4. Satellite send the result back to the Client


  • Server: Regular pdfToolbox Server/CLI license required
  • Dispatcher: Dispatcher pdfToolbox Server/CLI license required
  • Satellite: Regular pdfToolbox Server/CLI license required
  • Monitor: No license required
  • Client: No license required


Send Your Comment

E-Mail me when someone replies to this comment