IBeam Configuration

IBeam can be configured in many ways to suit your specific needs. This section lists all possible configuration settings and discusses some of them in more detail.

Environment Variables

To facilitate custom usage and become more future-proof, IBeam expects the following environment variables altering its behaviour:

General

Variable name	Default value	Description
IBEAM_INPUTS_DIR	/srv/inputs/	Directory path of Inputs Directory.
IBEAM_OUTPUTS_DIR	../outputs	Directory path of Outputs Directory.
IBEAM_GATEWAY_DIR	None	Path to the root of the IBKR Gateway.
IBEAM_CHROME_DRIVER_PATH	None	Path to the Chrome Driver executable file.
IBEAM_GATEWAY_STARTUP	20	How many seconds to wait for the Gateway to respond after its startup.
IBEAM_GATEWAY_PROCESS_MATCH	ibgroup.web.core.clientportal.gw.GatewayStart	The gateway process' name to match against.
IBEAM_MAINTENANCE_INTERVAL	60	How many seconds between each maintenance.
IBEAM_SPAWN_NEW_PROCESSES	False	Whether new processes should be spawned for each maintenance.
IBEAM_LOG_LEVEL	INFO	Verbosity level of the logger used.
IBEAM_LOG_TO_FILE	True	Whether logs should also be saved to a file.
IBEAM_REQUEST_RETRIES	1	How many times to reattempt a request to the gateway.
IBEAM_REQUEST_TIMEOUT	15	How many seconds to wait for a request to complete.

Gateway Routes

Variable name	Default value	Description
IBEAM_GATEWAY_BASE_URL	https://localhost:5000	Base URL of the gateway.
IBEAM_ROUTE_AUTH	/sso/Login?forwardTo=22&RL=1&ip2loc=on	Gateway route with authentication page.
IBEAM_ROUTE_USER	/v1/api/one/user	Gateway route with user information.
IBEAM_ROUTE_VALIDATE	/v1/portal/sso/validate	Gateway route with validation call.
IBEAM_ROUTE_REAUTHENTICATE	/v1/portal/iserver/reauthenticate?force=true	Gateway route with reauthentication call.
IBEAM_ROUTE_AUTH_STATUS	/v1/api/iserver/auth/status	Gateway route with authentication status call.
IBEAM_ROUTE_TICKLE	/v1/api/tickle	Gateway route with tickle call.

Authentication

Variable name	Default value	Description
IBEAM_USER_NAME_EL_ID	user_name	HTML element id containing the username input field.
IBEAM_PASSWORD_EL_ID	password	HTML element id containing the password input field.
IBEAM_SUBMIT_EL_ID	submitForm	HTML element id containing the submit button.
IBEAM_ERROR_EL_ID	ERRORMSG	HTML element id containing the submit button.
IBEAM_SUCCESS_EL_TEXT	Client login succeeds	HTML element text indicating successful authentication.
IBEAM_OAUTH_TIMEOUT	15	How many seconds to wait for the OAuth login request to complete.
IBEAM_PAGE_LOAD_TIMEOUT	15	How many seconds to wait for the login page to load.
IBEAM_ERROR_SCREENSHOTS	False	Whether to save login page screenshots on error.
IBEAM_MAX_FAILED_AUTH	5	Maximum number of failed authentication attempts.
IBEAM_MAX_IMMEDIATE_ATTEMPTS	10	Maximum number of immediate retries upon detecting an error message.

Two-Factor Authentication

Variable name	Default value	Description
IBEAM_TWO_FA_EL_ID	twofactbase	HTML element check for if Gateway will require 2FA authentication.
IBEAM_TWO_FA_INPUT_EL_ID	chlginput	HTML element to input 2FA code into
IBEAM_TWO_FA_HANDLER	None	Which 2FA handler should be used to acquire the code.
IBEAM_STRICT_TWO_FA_CODE	True	Whether to ensure only 2FA code made of 6 digits can be used.

Configuring Authentication

Gateway startup timeout

Upon starting the Gateway, IBeam will begin to repeatedly attempt to communicate with it every 1 second until the Gateway is ready or the startup timeout set by IBEAM_GATEWAY_STARTUP is reached.

Internal communication timeout

When monitoring the Gateway, IBeam will send it different requests that check for its health and authentication status. These requests may take long or fail at first attempt on some systems.

IBEAM_REQUEST_RETRIES and IBEAM_REQUEST_TIMEOUT allow you to set how many times IBeam will retry each such internal request to the Gateway, and how many seconds to wait for these to complete

Page load timeout

On some systems, the Gateway takes longer than usual to load the HTML page IBeam uses to authenticate. IBEAM_PAGE_LOAD_TIMEOUT defines how long IBeam will wait for the Gateway to load this page.

Authentication timeout

Once the page is loaded, IBeam will input the credentials and submit them, waiting for an update on the web page indicating that the request has completed. IBEAM_OAUTH_TIMEOUT defines how long IBeam will wait for the authentication request to complete.

Authentication retries

Upon observing a failure in the authentication request on the web page, IBeam will immediately attempt to reauthenticate. IBEAM_MAX_IMMEDIATE_ATTEMPTS defines the limit after which IBeam will stop authentication attempts and report a failure in authentication.

Max failed authentications

As of writing this, IBKR performs a 24-hour lock-out on an account upon 10 consecutive unsuccessful login attempts. Any successful login is meant to reset this counter.

To prevent this lock-out from happening, IBeam will count the amount of consecutive failed attempts and shut down if authentication fails too many times. The environment variable IBEAM_MAX_FAILED_AUTH defines the maximum number of failed authentication attempts that IBeam will allow. To disable this functionality, set this environment variable to a very large number.

Debugging

IBeam by default logs all information using a Python standard library's logging module, through a custom logger called 'ibeam'. The default log level is INFO, which you can set to DEBUG using the IBEAM_LOG_LEVEL variable.

All logs are saved to a file in the Outputs Directory. This behaviour can be disabled by setting IBEAM_LOG_TO_FILE to False.

Additionally, you can set IBEAM_ERROR_SCREENSHOTS to True in order for IBeam to attempt to save a screenshot upon encountering an error during authentication. All screenshots are saved in the Outputs Directory.

Maintenance interval

Once the Gateway is started and authenticated, IBeam will begin the maintenance, during which it will repeatedly check the health and authentication status of the Gateway and take appropriate actions if needed. The interval for this maintenance is set by IBEAM_MAINTENANCE_INTERVAL variable.

Changing Port

Before you start make sure you're familiar with providing a custom conf.yaml file through Inputs Directory.

1. Modify listenPort value in conf.yaml, eg: listenPort: 8000
2. Provide environment variable IBEAM_GATEWAY_BASE_URL with a URL modified to the port we want to set, eg: IBEAM_GATEWAY_BASE_URL=https://localhost:8000
3. Run IBeam, mapping the new port, eg. docker run -p 8000:8000

Then confirm that IBeam and Gateway are configured for the new port by running:

curl -X GET "https://localhost:8000/v1/api/one/user" -k

---

Next

Learn about Gateway Configuration