53
Configuring RoboServer
403
In order to make this scheme more flexible in actual implementation, it is possible to delegate the authority
to sign. That is, the signature on a certificate may not actually be from a third party that you trust, but
rather from yet another party who can display a certificate that you will trust. This may be extended to
any number of levels, representing a chain of trust. To make verification practical, the signed certificate
contains copies of all the certificates associated with the chain of trust (the last one being a self-signed
root certificate). At least one of the certificates in this chain should be previously trusted by you.
Certificates are used in four different ways on RoboServer, corresponding to the four properties on the
"Certificates" tab. Two of these have to do with how robots access web servers as part of their execution:
Verify HTTPS Certificates:
A robot may need to verify the identity of a web server that
it accesses (via HTTPS). Such a verification is routinely (and
invisibly) done by ordinary browsers in order to detect phishing
attacks. However, the verification often is not necessary when
robots collect information, because the robots only access those
well-known web sites that they have been written for. Thus the
verification it is not enabled by default.
If enabled, verification is done in the same way a browser does it:
The web server's certificate is checked based on an installed set of
trusted HTTPS certificates similar to those you can configure in a
browser.
HTTPS Client Certificates:
This is almost the same as described above, but in the opposite
direction. A robot may need to access a web server which wants to
verify the identity of the client (robot) that accesses it. Presumably
the web server contains confidential or commercial data that should
be passed on only to clients with a proven identity. This identity is
represented by a HTTPS client certificate.
Two other properties have to do with authentication in the communication between RoboServer and API
clients that want robots to be executed on RoboServer. These properties apply only when clients connect
to RoboServer via the secure socket based RQL protocol. The main purpose of the secure protocol is to
encrypt communication, but with a little configuration it will also provide authentication, i.e., identity
verification:
Verify API Client Certificates:
RoboServer is able to verify the identity of any client that connects
to it in order to execute robots. This verification is disabled by
default.
If enabled, the mechanics of verification is the same as for
HTTPS certificates even though the purpose is quite different. The
connecting client's certificate is checked based on an installed set
of trusted API client certificates.
API Server Certificate:
RoboServer also has a server certificate that it will present to
connecting clients. This certificate has a dual purpose: It makes the
encryption side of SSL work (for this reason RoboServer comes
with a default self-signed certificate), and it identifies this particular
RoboServer to the clients.
The default API server certificate is the same for all RoboServers
and thus is not any good for identification. If your clients need to
verify the identity of the RoboServer they connect to, as described
in SSL, you must create and install a unique API Server Certificate
for each RoboServer.
38
Configuring RoboServer
404
HTTPS Certificates
When a robot accesses a web site over HTTPS, it will verify the site's certificate (provided that the "Verify
HTTPS Certificates" checkbox is checked). Verification is done based two sets of trusted certificates: The
set of root certificates and an additional set of server certificates.
The root certificates are installed with Kapow Katalyst just as root certificates are installed with your
browser. They are found in the Certificates/Root folder in the application data folder.
Some HTTPS sites may use certificate authorities that are not included by default. In this case, you need
to install the appropriate certificates for Kapow Katalyst to load from these sites. Most often, these would
be installed in the Certificates/Server folder in the application data folder.
To be precise, it does not matter - for the purpose of handling HTTPS sites - whether you add certificates to
the set of root certificates or to the set of server certificates. However, please note that the root certificates
have a broader scope, as they are also used when checking API client certificates.
To install a certificate, you need to obtain the certificate as a PKCS#7 certificate chain, as a Netscape
certificate chain, or as a DER-encoded certificate. You install the certificate by copying it to either of the
two folders mentioned above. The name of the file containing the certificate does not matter.
The following example explains how to install a server certificate for the website https://www.foo.com.
The example is based on Internet Explorer.
• Open https://www.foo.com in Internet Explorer.
• Select “Properties” under the “File” menu, and then select “Certificates”. This will open a Certificate
dialog.
• Click “Install Certificate”.
• Click “Next” twice, “Finish” once, and exit the certificate dialog. Now you have installed the certificate
in your browser. The next step is to export it to a file.
• Click “Internet Options...” in the Tools menu. This opens the “Internet Options” dialog.
• Go to the “Content” tab and click on the “Certificates” button.
• Now you need to locate the installed certificate. It is most likely in the tab called “Other People”.
• Select the certificate and press “Export”.
• Press “Next” twice.
• Save the certificate in the Certificates/Server folder in the application data folder as foo.cer.
• Restart all your running RoboServers.
Note
You must install the certificates on all installations that need to load from the particular HTTPS
sites.
HTTPS Client Certificates
When a robot accesses a HTTPS site, it may need to provide its own certificate to the web server. This is
set up in the robot's Default Options [../ref/robomaker/reference/stepaction/support/BrowserEngine.html]
44
Configuring RoboServer
405
or in the step-specific Options. One way to provide the certificate is to reference one of those that have
been configured into the Kapow Katalyst installation.
To add a new client certificate, in the Certificates tab of RoboServer Settings click the icon below the list
of HTTPS client certificates. You will be prompted to select a certificate file which must be in PKCS12
format, and you must enter the password used to encrypt the file. When the certificate is first entered into
the list, it will be given a unique ID, which is later used in the robot to select the certificate. You can change
the ID by clicking the icon. Remember that the certificates must be configured into all Kapow Katalyst
installations that need to run the robot.
API Client Certificates
When API clients connect to RoboServer over SSL, RoboServer will verify the certificates presented
to it (provided that the "Verify API Client Certificates" checkbox is checked). Verification means that
RoboServer will reject connections from clients that fail verification, and is done based on two sets of
trusted certificates: The set of root certificates and an additional set of API client certificates.
The root certificates are installed with Kapow Katalyst just as root certificates are installed with your
browser. They are found in the Certificates/Root folder in the application data folder. These are the
same root certificates which are used for checking HTTPS certificates; however, root certificates probably
will play a much smaller role when verifying API clients.
This is because in most cases, you will create your own self-signed API client certificates rather than
use (expensive) certificates issued by official signing authorities. You should install your API client
certificates in the Certificates/API/TrustedClients folder in the application data folder so
that RoboServer will recognize them.
Technically speaking, it does not matter - for the purpose of verifying connecting API clients - whether
you add API client certificates to the set of root certificates or to the set of API client certificates. However
the guidelines given above will help you avoid problems caused by the fact that the root certificates are
also (even mainly) used when checking HTTPS certificates.
You can generate a self-signed certificate for your API client with the Java keytool command as follows:
keytool -genkey -keystore client.p12 -alias client -keyalg RSA -storetype "PKCS12"
You will be prompted for the following information: Name (domain), name of Organizational Unit,
Organization, City, State, Country and password. Do not forget the password, there is no way to retrieve
it if lost. This call of keytool will put the certificate into the keystore client.p12. You then must
extract it into a separate file:
keytool -export -keystore client.p12 -alias client -storetype "PKCS12" -file client.pub.cer
You will be prompted for the password used when the certificate was generated. The output file
client.pub.cer is what should be copied into the Certificates/API/TrustedClients
folder in the application data folder.
API Server Certificate
For technical reasons, RoboServer must have a server certificate that it can present to API clients when they
connect to it using SSL. During installation, a default self-signed certificate is installed. This certificate is
no good for identification purposes since it is the same for all RoboServers, and should be replaced if the
API clients need to verify the identity of the RoboServer.
If you want to use a certificate issued by a signing authority like VeriSign, you can import it by clicking
the "Change" button in the Certificates tab of RoboServer Settings. This will open a file selection dialog
37
Configuring RoboServer
406
and once the certificate is located, you will be prompted for the password. If the password is correct
the certificate will be imported, and you should see the certificate's Issued To, Issued By, and Expires
properties.
You can generate a new self-signed certificate for RoboServer by using the following Java keytool
command:
keytool -genkey -keystore server.p12 -alias server -keyalg RSA -storetype "PKCS12"
You will be prompted for the following information: Name (domain), name of Organizational Unit,
Organization, City, State, Country and password. Do not forget the password, there is no way to retrieve
it if lost. The certificate will be saved in the keystore file server.p12, which you can then import as
described.
Setting the Default RoboServer Project
You can set the location of the default RoboServer project folder in the 'Project' tab of RoboServer Settings.
By default, the folder will be set to the default robot project created in the installation folder by the
installation process. See the Design Studio User’s Guide for more information on robot projects.
The RoboServer default project is used only by the API. When executing a robot from the API, any
references it has to types, snippets or other resources are resolved by looking in the default project.
Configuring the JMX Server
The embedded JMX server can be used to monitor the running RoboServer through tools like JConsole. It
is enabled by providing an argument on the RoboServer command line (see the RoboServer User’s Guide
for further information.)
Hiding Sensitive Robot Input
The Show Inputs option controls whether robot input parameters are shown in the management interface.
This makes it possible to hide security sensitive information like passwords.
JMX Server Access
By default the JMX server can be accessed by all clients with access to the correct port on the server. By
selecting the Use Password option the chosen user name and password must be provided when connecting.
Heartbeat Notifications
If an interval (in seconds) greater than 0 is specified the JMX server sends out a heartbeat notification with
the given interval as long as the RoboServer is running and responding to queries.
Changing the RAM Allocation
As installed, each Kapow Katalyst application is configured with a maximum amount of RAM that it may
use. This amount usually is plenty for ordinary work, but if you run many robots in parallel on RoboServer,
or if some robots use much RAM, it may be necessary to increase the allocation.
You can change the allocation for any of the applications by editing its .conf file, found in the bin
subfolder of the installation. For RoboServer, the file to edit is named:
12
Configuring RoboServer
407
bin/RoboServer.conf
You need add a line with:
wrapper.java.maxmemory=1024
For example, in order to permit RoboServer to use up to 4GB of RAM, add this line:
wrapper.java.maxmemory=4096
(Note that an allocation this high is possible only on the 64-bit version of Kapow Katalyst).
Also note that the .conf file can be edited only by the user who installed Kapow Katalyst (e.g., typically
the administrator on Windows).
If necessary, the maximum RAM allocation for other Kapow Katalyst applications can be changed in the
same way.
28
408
Control Center User's Guide
Control Center is a legacy application for managing RoboServers. Most monitoring and administration of
RoboServers and robots are today done using the Management Console. For old setups that do not take
advantage of the Management Console, Control Center can be used. Control Center also allows monitoring
of robots runs that have been initiated by communication from a Java or .NET client directly to RoboServer
and provides progress information on the robot runs.
Organization
The guide is divided into sections covering:
• Basic concepts.
• The user interface.
• How to use Control Center to manage RoboServers.
• How to use Control Center to manage robots.
• Miscellaneous other Control Center features.
Control Center Basics
This section describes the basic concepts used in the Control Center.
The Control Center has the following main tasks:
• Monitoring and shutting down RoboServers.
• Monitoring and stopping robots on RoboServers.
• Various administrative tasks.
In order for the Control Center to manage a RoboServer, you must register the RoboServer with the
Control Center. Registering a RoboServer simply means adding it to the list of RoboServers that can be
managed by the Control Center.
Control Center User Interface
This section gets you started with using the Control Center by introducing you to the user interface of
the application.
The Main Window
The main window of the Control Center is shown below:
Documents you may be interested
Documents you may be interested
