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	UNDEFINED	Path to the root of the IBKR Gateway.
IBEAM_CHROME_DRIVER_PATH	UNDEFINED	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_LOG_FORMAT	%(asctime)s	%(levelname)-.1s
IBEAM_REQUEST_RETRIES	2	How many times to reattempt a request to the gateway.
IBEAM_REQUEST_TIMEOUT	15	How many seconds to wait for a request to complete.
IBEAM_RESTART_FAILED_SESSIONS	True	Whether Gateway should be restarted on failed sessions.
IBEAM_RESTART_WAIT	15	How many seconds to wait for a restart to complete.
IBEAM_REAUTHENTICATE_WAIT	15	How many seconds to wait for a reauthentication to complete.
IBEAM_HEALTH_SERVER_PORT	5001	Port to start health server on.
IBEAM_SECRETS_SOURCE	env	Source of secrets.
IBEAM_GCP_SECRETS_URL	None	Base URL for GCP secrets manager.
IBEAM_START_ACTIVE	True	Whether IBeam should start activated or dormant.

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_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_INITIALISE	/v1/api/iserver/auth/ssodh/init	Gateway route with session initialisation 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.
IBEAM_ROUTE_LOGOUT	/v1/api/logout	Gateway route with logout call.

Authentication

Variable name	Default value	Description
IBEAM_USER_NAME_EL	None	HTML element name attribute containing the username input field.
IBEAM_PASSWORD_EL	NAME@@password	HTML element name attribute containing the password input field.
IBEAM_SUBMIT_EL	CSS_SELECTOR@@.btn.btn-lg.btn-primary	HTML element name attribute containing the submit button.
IBEAM_ERROR_EL	None	HTML element class name attribute containing the submit button.
IBEAM_SUCCESS_EL_TEXT	TAG_NAME@@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_MIN_PRESUBMIT_BUFFER	5	Minimum number of seconds to wait before hitting the submit button
IBEAM_MAX_PRESUBMIT_BUFFER	30	Maximum number of seconds to wait before hitting the submit button
IBEAM_MAX_IMMEDIATE_ATTEMPTS	10	Maximum number of immediate retries upon detecting an error message.
IBEAM_IBKEY_PROMO_EL_CLASS	CLASS_NAME@@ibkey-promo-skip	HTML element class containing the ibkey promo skip button.
IBEAM_AUTHENTICATION_STRATEGY	B	The authentication strategy used by IBeam.
IBEAM_MAX_STATUS_CHECK_RETRIES	120	How many times to reattempt the status check.
IBEAM_MAX_REAUTHENTICATE_RETRIES	3	How many times to reattempt the reauthentication before restarting the Gateway.
IBEAM_UI_SCALING	1	The resolution UI scaling to be used by the browser.

Two-factor Authentication

Variable name	Default value	Description
IBEAM_TWO_FA_EL_ID	ID@@twofactbase	HTML element check for if Gateway will require 2FA code authentication.
IBEAM_TWO_FA_NOTIFICATION_EL	CLASS_NAME@@login-step-notification	HTML element check for if Gateway will require 2FA notification authentication.
IBEAM_TWO_FA_INPUT_EL_ID	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.
IBEAM_TWO_FA_SELECT_EL_ID	ID@@sf_select	HTML element check for if Gateway requires to select the 2FA method.
IBEAM_TWO_FA_SELECT_TARGET	IB Key	Option that is to be chosen in the 2FA select dropdown
IBEAM_CUSTOM_TWO_FA_HANDLER	custom_two_fa_handler.CustomTwoFaHandler	Fully qualified path of the custom 2FA handler in the inputs directory.

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