diff options
-rw-r--r-- | .gitignore | 4 | ||||
-rw-r--r-- | PKGBUILD | 4 | ||||
-rw-r--r-- | README.md | 113 |
3 files changed, 118 insertions, 3 deletions
diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000000..3f20c6e06904 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +*.xz +*.gz +pkg +src @@ -1,13 +1,11 @@ # Maintainer: Ben Alex <ben.alex@acegi.com.au> -# Using GitHub as upstream URL instead of IBController, as GitHub has lots of docs on usage to assist users. - pkgname=ib-controller pkgver=2.12 pkgrel=3 pkgdesc='Manages headless Interactive Brokers IB Gateway instances' arch=('any') -url="https://github.com/benalexau/ibcontroller-aur" +url="https://github.com/ib-controller/ib-controller" license=('GPL3') depends=(ib-tws xorg-server-xvfb xorg-server gtk2 libxrender libxtst gsettings-desktop-schemas ttf-dejavu) diff --git a/README.md b/README.md new file mode 100644 index 000000000000..fa4b55b57e5d --- /dev/null +++ b/README.md @@ -0,0 +1,113 @@ +IBController AUR +================= +Source and documentation for the +[IBController](https://github.com/ib-controller/ib-controller) +AUR package [ib-controller](https://aur.archlinux.org/packages/ib-controller/). +This allows you to control [Interactive Brokers](http://interactivebrokers.com/) +[Trader Workstation](http://www.interactivebrokers.com/en/pagemap/pagemap_APISolutions.php). + +This package depends on Trader Workstation having been installed via AUR package +[ib-tws](https://aur.archlinux.org/packages/ib-tws/). It installs a custom build +of IBController and a headless +[systemd](http://en.wikipedia.org/wiki/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](package/fdemo.ini), +or ``ibcontroller@edemo.service`` for the included +[individual user sample INI file](package/edemo.ini). Both sample INI files can +be used concurrently, as they bind to unique ports. Please refer to the +[IBController](https://github.com/ib-controller/ib-controller) 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](http://mmonit.com/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/](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 +```` |