Documentation fixes by bp-alex · Pull Request #2 · ib-controller/ib-controller
Expand Up
@@ -9,7 +9,7 @@ For more recent versions, the following instructions apply.
Distribution Contents --------------------- IB TWS and IB Controller are both IB TWS and IBController are both [Java](https://www.java.com) applications. The distribution ZIP files contain:
Expand All @@ -23,30 +23,30 @@ Source code and build scripts are not included in the distribution ZIPs, as they are freely available from the [GitHub project page](https://github.com/ib-controller/ib-controller).
Aside from IB Controller, you will need to download and install IB Aside from IBController, you will need to download and install IB [Trader Workstation](http://www.interactivebrokers.com/en/pagemap/pagemap_APISolutions.php). You do not need an IB account to try out IB Controller, as you can use the IB You do not need an IB account to try out IBController, as you can use the IB demo account (username ``edemo``, password ``demouser``).
Default Paths ------------- Several sample files ship in each IB Controller release. Your main installation Several sample files ship in each IBController release. Your main installation task is to edit these sample files to suit your particular needs. The sample files (and these instructions) assume the following default paths:
| Platform | Product | Path | | -------- | ------------- | --------------------------------------------------- | | Windows | IB TWS | ``C:\Jts`` | | Windows | IB Controller | ``C:\IBController`` | | Windows | IBController | ``C:\IBController`` | | Unix | IB TWS | ``/opt/IBJts`` | | Unix | IB Controller | ``/opt`` | | Unix | IBController | ``/opt`` |
Note that installing IB Controller and/or TWS from a Linux package manager will Note that installing IBController and/or TWS from a Linux package manager will not use these paths. Consult your Linux package instructions for file locations.
Installation ------------ Installing IB Controller is just a matter of unzipping the download file to Installing IBController is just a matter of unzipping the download file to wherever you want to install it. A Linux user might use something like:
``` Expand All @@ -56,30 +56,30 @@ sudo unzip ~/Downloads/IBControllerV1.2.3.zip
Password Security ----------------- To logon to TWS or IB Gateway, IB Controller needs to know your Interactive To logon to TWS or IB Gateway, IBController needs to know your Interactive Brokers username and password. You should very carefully secure your IB account username and password. Your main options are:
1. Store the password in the IB Controller configuration ``.ini`` file and 1. Store the password in the IBController configuration ``.ini`` file and rely on operating system security to protect it. This is strongly recommended, although complex for many users to implement. Linux users should use any operating system packages available for their distribution, as these have probably implemented the recommended security option (although check the package documentation for details). 2. Store the password in the IB Controller configuration ``.ini`` file and 2. Store the password in the IBController configuration ``.ini`` file and use the encrypted encoding option. Please note that encrypted encoding is easily reversed. It should not be relied upon on its own. 3. Pass the password as a command line parameter. This is strongly discouraged as command line information is available in many places on your computer (eg shell histories, process lists etc).
To encrypt your password (ie for option 2 above), run the following command from the IB Controller directory: the IBController directory:
``java -cp IBController.jar ibcontroller.IBController encrypt <your-password>``
The program output will include your encrypted password, which can then be included in your IB Controller configuration ``.ini`` file. You should also included in your IBController configuration ``.ini`` file. You should also clear your shell history if you entered the above command. In most cases this is achieved by pressing ALT+F7 (Windows users) or typing ``history -c`` (Linux), although you should check it worked by pressing the up arrow afterwards. Expand All @@ -96,19 +96,19 @@ edit the ``IbLoginID`` and ``IbPassword`` options at minimum. The ``PasswordEncrypted`` setting should be set to ``yes`` if you used the aforementioned encrypted password encoding option.
There are two ways that IB Controller can locate your edited ``.ini`` file. The There are two ways that IBController can locate your edited ``.ini`` file. The simplest way is to tell it where to find the file. If you do this, you can give the configuration file any name you like. This is the recommended approach, but will require you to edit the execution shell script (details below).
If you do not specify a configuration file name, IB Controller will expect to If you do not specify a configuration file name, IBController will expect to find a file named ``IBController.<username>.ini`` in the current working directory. In this case, ``<username>`` is your username on your computer (not your IB account username).
Launching --------- The normal way to start IB Controller is by use of a shell script. These can The normal way to start IBController is by use of a shell script. These can be identified by the ``.bat`` (Windows) or ``.sh`` (Unix) extensions. The purpose of each shell script was mentioned in the "Distribution Contents" section above. Expand All @@ -121,7 +121,7 @@ Windows users can execute a shell script in a number of ways, including:
Most users will not need to edit the launch shell scripts in any significant manner. The most likely edit is to specify the path to your configuration ``.ini`` file. The command for running IB Controller has the following form: ``.ini`` file. The command for running IBController has the following form:
``java -cp <classpath> <otherOptions> <entryPoint> [<config file>|NULL] [<loginId> <password>]``
Expand All @@ -132,15 +132,15 @@ protected by suitable operating system file permissions).
Headless Execution (Unix) ------------------------- IB Controller can operate without a display via a virtual framebuffer. Refer IBController can operate without a display via a virtual framebuffer. Refer to the Arch Linux [ib-controller](https://aur.archlinux.org/packages/ib-controller/) AUR package for a good example of headless operation (as well as other considerations you'd typically need for a server, such as systemd configuration, ``/etc`` directory file permissions etc).
Scheduled Tasks (Windows) ------------------------- On Windows you can start IB Controller automatically using a Scheduled Task. On Windows you can start IBController automatically using a Scheduled Task.
If you do this, you must make sure that the machine is already logged on before the scheduled task runs. Otherwise the task will still run, but you won't be Expand All @@ -149,12 +149,12 @@ able to see and interact with TWS, even if you subsequently log on. Remember also to change the task settings to prevent Windows automatically ending it after a certain time.
Also you can use the ``IbAutoClosedown=no`` setting in the IB Controller Also you can use the ``IbAutoClosedown=no`` setting in the IBController configuration file to disable TWS's autologoff feature, and the ``ClosedownAt=``setting to specify when IB Controller will shut down TWS. ``ClosedownAt=``setting to specify when IBController will shut down TWS.
Questions? ---------- Lots of people use IB Controller and are happy to assist you! Please see the Lots of people use IBController and are happy to assist you! Please see the [support information](https://github.com/ib-controller/ib-controller#support) for details.
Distribution Contents --------------------- IB TWS and IB Controller are both IB TWS and IBController are both [Java](https://www.java.com) applications. The distribution ZIP files contain:
Expand All @@ -23,30 +23,30 @@ Source code and build scripts are not included in the distribution ZIPs, as they are freely available from the [GitHub project page](https://github.com/ib-controller/ib-controller).
Aside from IB Controller, you will need to download and install IB Aside from IBController, you will need to download and install IB [Trader Workstation](http://www.interactivebrokers.com/en/pagemap/pagemap_APISolutions.php). You do not need an IB account to try out IB Controller, as you can use the IB You do not need an IB account to try out IBController, as you can use the IB demo account (username ``edemo``, password ``demouser``).
Default Paths ------------- Several sample files ship in each IB Controller release. Your main installation Several sample files ship in each IBController release. Your main installation task is to edit these sample files to suit your particular needs. The sample files (and these instructions) assume the following default paths:
| Platform | Product | Path | | -------- | ------------- | --------------------------------------------------- | | Windows | IB TWS | ``C:\Jts`` | | Windows | IB Controller | ``C:\IBController`` | | Windows | IBController | ``C:\IBController`` | | Unix | IB TWS | ``/opt/IBJts`` | | Unix | IB Controller | ``/opt`` | | Unix | IBController | ``/opt`` |
Note that installing IB Controller and/or TWS from a Linux package manager will Note that installing IBController and/or TWS from a Linux package manager will not use these paths. Consult your Linux package instructions for file locations.
Installation ------------ Installing IB Controller is just a matter of unzipping the download file to Installing IBController is just a matter of unzipping the download file to wherever you want to install it. A Linux user might use something like:
``` Expand All @@ -56,30 +56,30 @@ sudo unzip ~/Downloads/IBControllerV1.2.3.zip
Password Security ----------------- To logon to TWS or IB Gateway, IB Controller needs to know your Interactive To logon to TWS or IB Gateway, IBController needs to know your Interactive Brokers username and password. You should very carefully secure your IB account username and password. Your main options are:
1. Store the password in the IB Controller configuration ``.ini`` file and 1. Store the password in the IBController configuration ``.ini`` file and rely on operating system security to protect it. This is strongly recommended, although complex for many users to implement. Linux users should use any operating system packages available for their distribution, as these have probably implemented the recommended security option (although check the package documentation for details). 2. Store the password in the IB Controller configuration ``.ini`` file and 2. Store the password in the IBController configuration ``.ini`` file and use the encrypted encoding option. Please note that encrypted encoding is easily reversed. It should not be relied upon on its own. 3. Pass the password as a command line parameter. This is strongly discouraged as command line information is available in many places on your computer (eg shell histories, process lists etc).
To encrypt your password (ie for option 2 above), run the following command from the IB Controller directory: the IBController directory:
``java -cp IBController.jar ibcontroller.IBController encrypt <your-password>``
The program output will include your encrypted password, which can then be included in your IB Controller configuration ``.ini`` file. You should also included in your IBController configuration ``.ini`` file. You should also clear your shell history if you entered the above command. In most cases this is achieved by pressing ALT+F7 (Windows users) or typing ``history -c`` (Linux), although you should check it worked by pressing the up arrow afterwards. Expand All @@ -96,19 +96,19 @@ edit the ``IbLoginID`` and ``IbPassword`` options at minimum. The ``PasswordEncrypted`` setting should be set to ``yes`` if you used the aforementioned encrypted password encoding option.
There are two ways that IB Controller can locate your edited ``.ini`` file. The There are two ways that IBController can locate your edited ``.ini`` file. The simplest way is to tell it where to find the file. If you do this, you can give the configuration file any name you like. This is the recommended approach, but will require you to edit the execution shell script (details below).
If you do not specify a configuration file name, IB Controller will expect to If you do not specify a configuration file name, IBController will expect to find a file named ``IBController.<username>.ini`` in the current working directory. In this case, ``<username>`` is your username on your computer (not your IB account username).
Launching --------- The normal way to start IB Controller is by use of a shell script. These can The normal way to start IBController is by use of a shell script. These can be identified by the ``.bat`` (Windows) or ``.sh`` (Unix) extensions. The purpose of each shell script was mentioned in the "Distribution Contents" section above. Expand All @@ -121,7 +121,7 @@ Windows users can execute a shell script in a number of ways, including:
Most users will not need to edit the launch shell scripts in any significant manner. The most likely edit is to specify the path to your configuration ``.ini`` file. The command for running IB Controller has the following form: ``.ini`` file. The command for running IBController has the following form:
``java -cp <classpath> <otherOptions> <entryPoint> [<config file>|NULL] [<loginId> <password>]``
Expand All @@ -132,15 +132,15 @@ protected by suitable operating system file permissions).
Headless Execution (Unix) ------------------------- IB Controller can operate without a display via a virtual framebuffer. Refer IBController can operate without a display via a virtual framebuffer. Refer to the Arch Linux [ib-controller](https://aur.archlinux.org/packages/ib-controller/) AUR package for a good example of headless operation (as well as other considerations you'd typically need for a server, such as systemd configuration, ``/etc`` directory file permissions etc).
Scheduled Tasks (Windows) ------------------------- On Windows you can start IB Controller automatically using a Scheduled Task. On Windows you can start IBController automatically using a Scheduled Task.
If you do this, you must make sure that the machine is already logged on before the scheduled task runs. Otherwise the task will still run, but you won't be Expand All @@ -149,12 +149,12 @@ able to see and interact with TWS, even if you subsequently log on. Remember also to change the task settings to prevent Windows automatically ending it after a certain time.
Also you can use the ``IbAutoClosedown=no`` setting in the IB Controller Also you can use the ``IbAutoClosedown=no`` setting in the IBController configuration file to disable TWS's autologoff feature, and the ``ClosedownAt=``setting to specify when IB Controller will shut down TWS. ``ClosedownAt=``setting to specify when IBController will shut down TWS.
Questions? ---------- Lots of people use IB Controller and are happy to assist you! Please see the Lots of people use IBController and are happy to assist you! Please see the [support information](https://github.com/ib-controller/ib-controller#support) for details.