IBController AUR

Source and documentation for the IBController AUR package ib-controller. This allows you to control Interactive Brokers Trader Workstation.

This package depends on Trader Workstation having been installed via AUR package ib-tws. It installs a custom build of IBController and a headless systemd configuration that supports multiple concurrent IB Gateway instances while addressing usual security needs.

To start IBController and the IB Gateway it manages, create an INI file in /etc/ibcontroller and use systemd commands such as:

sudo systemctl start ibcontroller@ininame.service
sudo systemctl enable ibcontroller@ininame.service

The aforementioned ininame should be the simple name of an /etc/ibcontroller INI file. For example, use ibcontroller@fdemo.service for the included financial advisor sample INI file, or ibcontroller@edemo.service for the included individual user sample INI file. Both sample INI files can be used concurrently, as they bind to unique ports. Please refer to the IBController documentation for the meaning of individual INI configuration settings.

Please note future updates to this package may change the sample INI files to reflect new configuration defaults. You should create your own INI file(s) rather than editing one of the shipped INI files. Similarly the systemd configuration file may be changed in future updates.

Monitoring

If you'd like to monitor your IBController is running and IB API is available, Monit is recommended. It's easily installed with sudo pacman -S monit. Edit the /etc/monitrc file and add lines like:

set daemon 60
set mailserver mail.someisp.com
set alert you@you.com not on { instance, action }

check process ib-api-fdemo matching 'xvfb.*java.*fdemo.ini'
  start program = "/usr/sbin/systemctl start ibcontroller@fdemo.service"
  stop program = "/usr/sbin/systemctl stop ibcontroller@fdemo.service"
  if failed host 127.0.0.1 port 4002
    send "63\0x0071\0x001\0x005556\0x00" # clientVer\startAPI\startApiVer\5556
    expect "[0-9]{2,}"                   # serverVer reply
    send "49\0x001\0x00"                 # reqCurrTime\reqCurrTimeVer
    expect "49"                          # serverTime reply
  then restart

In the above:

• The daemon statement causes service monitoring every 60 seconds.
• The matching regular expression detects the fdemo.ini IBController process. Monit will then report additional statistics in the Monit interface (eg CPU/RAM use) plus detect if the process is not running.
• The if failed host check on port 4002 performs an IB API connection handshake and requests the server time. This offers confidence IB API is running.
• The restart directive will both restart the service and send an email if there is any issue detected.

Don't forget you'll need to start Monit after editing the /etc/monitrc:

sudo systemctl start monit
sudo systemctl enable monit

You can use http://localhost:2812/ (default username admin, password monit) to access the Monit GUI.

Security

Always ensure the /etc/ibcontroller INI files are only readable by root, as they contain your IB credentials. If you require additional credential safety you may like to consider the IBController PasswordEncrypted option, however it is easily decrypted and therefore not used in the sample files.

There is no mechanism to use IB hardware security tokens with the systemd configuration. This is due to the systemd configuration using a virtual framebuffer, so there is no mechanism by which hardware challenges can be presented. If you have a hardware token, you can disable it for trading system access via IB Account Management. Alternately you may like to create a new user account under your IB account which has trading access but no hardware token.

Only 127.0.0.1 is trusted by the resulting IB Gateway instance. Port forwarding (eg iptables, SSH tunneling) is suggested if other IP addresses are required.

Build and Test

If you'd like to try out changes to the package, these commands offer a start:

cd package
rm -rf pkg src *.xz *.gz && makepkg -f
namcap -m *.xz
sudo pacman -U *.xz
sudo systemctl daemon-reload
sudo systemctl start ibcontroller@fdemo.service
sudo systemctl status ibcontroller@fdemo.service
sudo systemctl stop ibcontroller@fdemo.service
rm -f *.gz && mkaurball
burp -c daemons *.gz