1 files changed, 113 insertions, 0 deletions
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
+````