### Start Gateway (Windows)

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/GettingStarted.md

Command to start the Client Portal Gateway on Windows systems. It requires navigating to the gateway's installation directory and executing the run batch file with the configuration file path.

```batch
cd C:\gateway
bin\run.bat root\conf.yaml
```

--------------------------------

### Start Gateway (Linux/macOS)

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/GettingStarted.md

Command to start the Client Portal Gateway on Linux or macOS systems. It requires navigating to the gateway's installation directory and executing the run script with the configuration file path.

```shell
cd /path/to/gateway
./bin/run.sh root/conf.yaml
```

--------------------------------

### Start IBeam Standalone Gateway

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Starts the IBeam Gateway using the standalone Python script. When run without arguments, it starts the gateway and attempts authentication if not already authenticated. Requires additional environment setup.

```shell
python ibeam_starter.py
```

--------------------------------

### Start IBeam Standalone

Source: https://github.com/voyz/ibeam/blob/master/README.md

Instructions for starting the IBeam service when installed as a standalone Python package. This typically involves running a starter script.

```python
python ibeam_starter.py
```

--------------------------------

### Install IBeam Standalone

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Installs the IBeam Python package using pip. This method requires manual setup of the standalone environment and its dependencies.

```shell
pip install ibeam
```

--------------------------------

### Start IBeam with Docker

Source: https://github.com/voyz/ibeam/blob/master/README.md

Guides for starting the IBeam service using Docker. This includes direct Docker run commands with environment variables and a more structured approach using Docker Compose with an environment file.

```shell
docker run --env IBEAM_ACCOUNT=your_account123 --env IBEAM_PASSWORD=your_password123 -p 5000:5000 voyz/ibeam
```

```yaml
services:
  ibeam:
    image: voyz/ibeam
    container_name: ibeam
    env_file:
      - env.list
    ports:
      - 5000:5000
      - 5001:5001
    network_mode: bridge # Required due to clientportal.gw IP whitelist
    restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded
```

```shell
docker compose up -d
```

--------------------------------

### Start IBeam using Starter Script with Parameters

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Executes the `starter.sh` script to launch the IBeam container, allowing customization of the image tag and environment file. This simplifies the start process with correct configuration.

```shell
. starter.sh -t 0.4.4 -e env_secondary.list
```

--------------------------------

### Start IBeam Docker with env.list

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Starts the IBeam Docker container, exposing port 5000 and loading environment variables from an env.list file. This is a convenient way to manage credentials and configuration.

```shell
docker run --env-file env.list -p 5000:5000 voyz/ibeam
```

--------------------------------

### Setup Docker Buildx for Multi-Platform Builds

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

Initializes the Docker buildx environment for building multi-platform images. This involves installing buildx from source, setting up the plugin, and configuring a builder instance with QEMU support.

```shell
export DOCKER_BUILDKIT=1
docker build --platform=local -o . git://github.com/docker/buildx
mkdir -p ~/.docker/cli-plugins
mv buildx ~/.docker/cli-plugins/docker-buildx
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker buildx create --name builder --driver docker-container --use
docker buildx inspect --bootstrap
```

--------------------------------

### Install IBeam with Docker

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Installs the Voyz IBeam Docker image from Docker Hub. This is the recommended installation method for ease of use and consistent environment.

```shell
docker pull voyz/ibeam
```

--------------------------------

### RDP Server Setup Commands

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Commands to configure a server for Remote Desktop Protocol (RDP) access. This includes updating packages, installing xrdp, configuring the firewall, installing a desktop environment (XFCE4), and enabling the xrdp service.

```shell
sudo apt-get update
sudo apt-get install -y xrdp
sudo ufw allow 3389/tcp
sudo apt-get install -y xfce4
echo xfce4-session > ~/.xsession
sudo systemctl enable xrdp
sudo systemctl start xrdp
```

--------------------------------

### Install IBeam

Source: https://github.com/voyz/ibeam/blob/master/README.md

Instructions for installing the IBeam tool. It can be installed using Docker for a containerized environment or via pip for standalone Python usage.

```docker
docker pull voyz/ibeam
```

```shell
pip install ibeam
```

--------------------------------

### IBeam Gateway API Verification

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Verifies the status of the IBeam Gateway by making a GET request to the authentication status endpoint. This command can be used with both Docker and standalone installations.

```APIDOC
GET /v1/api/iserver/auth/status

Description:
  Checks the authentication status of the IBeam Gateway.

Parameters:
  None directly in the URL, but requires the gateway to be running and accessible.

Request:
  - Method: GET
  - URL: https://localhost:5000/v1/api/iserver/auth/status
  - Headers:
    - Accept: application/json
  - Body: None

Response:
  - Status Code: 200 OK (if authenticated and running)
  - Body:
    {
      "authenticated": true,
      "connected": true,
      "can_use_concurrent_sessions": true,
      "is_fully_authenticated": true
    }

Usage Example:
  curl -X GET "https://localhost:5000/v1/api/iserver/auth/status" -k

Notes:
  - The '-k' flag is used to bypass SSL certificate verification, which might be necessary for local testing.
```

--------------------------------

### IBeam Starter Script Flags

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Lists the available command-line flags for the ibeam_starter.py script, used for managing the standalone IBeam Gateway. These flags control starting, stopping, maintaining, and querying the gateway's state.

```APIDOC
ibeam_starter.py [flags]

Description:
  Entrypoint script for managing the standalone IBeam Gateway.

Flags:
  -a, --authenticate
    Description: Authenticate the currently running gateway.
    Type: boolean

  -k, --kill
    Description: Kill the gateway process.
    Type: boolean

  -m, --maintain
    Description: Maintain the gateway (e.g., keep it running).
    Type: boolean

  -s, --start
    Description: Start the gateway if it is not already running.
    Type: boolean

  -t, --tickle
    Description: Send a tickle signal to the gateway (often used to keep sessions alive).
    Type: boolean

  -u, --user
    Description: Retrieve and display user information.
    Type: boolean

  -c, --check
    Description: Check if the current session is authenticated.
    Type: boolean

  -v, --verbose
    Description: Enable more verbose output for runtime information.
    Type: boolean
    Usage: Can be supplied with any other flag.
```

--------------------------------

### Start IBeam Docker with Direct Environment Variables

Source: https://github.com/voyz/ibeam/wiki/Installation-and-startup

Starts the IBeam Docker container, exposing port 5000 and providing environment variables directly via the command line. This is useful for quick tests or when an env.list file is not available.

```shell
docker run --env IBEAM_ACCOUNT=your_account123 --env IBEAM_PASSWORD=your_password123 -p 5000:5000 voyz/ibeam
```

--------------------------------

### Voyz IBeam Full Setup Script

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

A comprehensive bash script to automate the setup of the Voyz IBeam application. It handles argument validation, directory creation, generation of configuration files (env.list, conf.yaml), setting up a systemd autostart service for Docker, and creating a starter script for launching the IBeam container.

```bash
#!/bin/bash

# Ensure exactly two arguments are provided
if [[ $# -ne 2 ]]; then
  echo "Proper usage: $0 <IBKR account name> <IBKR account password>"
  exit 1
fi

echo "Beginning setup..."

# Establish IBeam configuration directories
echo "Constructing IBeam configuration directories..."
mkdir -p /root/ibeam_files/outputs
chmod 777 /root/ibeam_files/outputs
mkdir /root/ibeam_files/inputs_directory

# Generate environment variable file
echo "Generating environment variables file at /root/ibeam_files/env.list..."
cat <<EOF > /root/ibeam_files/env.list
IBEAM_ACCOUNT=$1
IBEAM_PASSWORD=$2
IBEAM_OUTPUTS_DIR=/srv/outputs
EOF

# Generate conf.yaml for IBeam Gateway configuration
echo "Generating Gateway config file at /root/ibeam_files/inputs_directory/conf.yaml..."
cat <<EOF > /root/ibeam_files/inputs_directory/conf.yaml
ip2loc: "US"
proxyRemoteSsl: true
proxyRemoteHost: "https://api.ibkr.com"
listenPort: 5000
listenSsl: true
ccp: false
svcEnvironment: "v1"
sslCert: "vertx.jks"
sslPwd: "mywebapi"
authDelay: 3000
portalBaseURL: ""
serverOptions:
  blockedThreadCheckInterval: 1000000
  eventLoopPoolSize: 20
  workerPoolSize: 20
  maxWorkerExecuteTime: 100
  internalBlockingPoolSize: 20
cors:
  origin.allowed: "*"
  allowCredentials: false
webApps:
  - name: "demo"
    index: "index.html"
ips:
  allow:
    - 10.*
    - 192.*
    - 131.216.*
    - 127.0.0.1
    - 0.0.0.0
    - 172.17.0.*
  deny:
    - 212.90.324.10
EOF

# Set up IBeam autostart service
echo "Setting up autostart service at /etc/systemd/system/ibeam_autostart.service..."
cat <<EOF > /etc/systemd/system/ibeam_autostart.service
[Unit]
Description=IBeam container
Requires=docker.service
After=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker start -a ibeam
ExecStop=/usr/bin/docker stop -t 2 ibeam

[Install]
WantedBy=default.target
EOF

sudo systemctl enable ibeam_autostart.service

# Create starter script
echo "Creating IBeam starter script at starter.sh..."
cat <<EOF > starter.sh
#!/bin/bash

# Default script parameters
ENV="env.list"
TAG="latest"
IBEAM_FILES="/root/ibeam_files"
CONTAINER_NAME="ibeam"

# Parse command-line arguments
while [[ $# -gt 0 ]]; do
  key="$1"
  case $key in
    -e|--env) 
      ENV="$2"
      shift # past argument
      shift # past value
      ;;
    -t|--tag) 
      TAG="$2"
      shift # past argument
      shift # past value
      ;;
    -i|--ibeam_files) 
      IBEAM_FILES="$2"
      shift # past argument
      shift # past value
      ;;
    -n|--name) 
      CONTAINER_NAME="$2"
      shift # past argument
      shift # past value
      ;;
    *)    
      echo "Unrecognized option: $1"
      shift # past argument
      ;;
  esac
done

echo "Environment variables file: $ENV"
echo "IBeam Docker image tag: $TAG"
echo "Container name: $CONTAINER_NAME"
echo "Directory for IBeam files: $IBEAM_FILES"

echo "Removing any existing IBeam container..."
docker rm -f ibeam

echo "Launching IBeam..."
docker run -d --env-file "$IBEAM_FILES/$ENV" --name "$CONTAINER_NAME" -p 5000:5000 -v "$IBEAM_FILES/inputs_directory/:/srv/inputs" -v "$IBEAM_FILES/outputs:/srv/outputs:rw" voyz/ibeam:$TAG
EOF

# Fetch and display server's IP address
MY_IP=$(ip -o route get to 8.8.8.8 | sed -n 's/.*src \([0-9.]\+\).*/\1/p')
cat << EOF



Setup completed!

Next steps:
1. Remotely connect to this server using its IP address: $MY_IP
2. Verify the configuration files in '/root/ibeam_files' directory
3. Start IBeam using the 'starter.sh' file
EOF
```

--------------------------------

### IBeam IP Allow Configuration

Source: https://github.com/voyz/ibeam/wiki/Troubleshooting

Example `conf.yaml` snippet demonstrating how to specify allowed IP addresses to resolve 'Access Denied' errors in IBeam Gateway. This configuration allows requests from specific IP ranges by listing them under `ips/allow`.

```yaml
ips:
  allow:
    10.148.0.0
    10.149.*
```

--------------------------------

### Install Firefox Web Browser

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Installs the Firefox web browser, providing internet access capabilities for the server. This command uses the apt package manager.

```shell
sudo apt install firefox
```

--------------------------------

### IBeam Configuration File Structure

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Illustrates the expected directory structure created by the setup script, including input configuration files and output directories.

```yaml
root
└───ibeam_files
    ├───inputs_directory
    │   └───conf.yaml
    ├───outputs
    └───env.list
```

--------------------------------

### Install Gnome System Monitor

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Installs the Gnome System Monitor package, a graphical tool for tracking system resources like CPU, memory, and network usage. It is recommended to keep this active to prevent memory overuse.

```shell
sudo apt-get install gnome-system-monitor
```

--------------------------------

### Execute Setup Script for IBeam Deployment

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Runs the `setup.sh` script to configure the IBeam environment, requiring IBKR account credentials. It sets up the necessary directory structure for IBeam files.

```shell
. setup.sh [YOUR IBKR ACCOUNT NAME] [YOUR IBKR ACCOUNT PASSWORD]
```

--------------------------------

### Verify IBeam Gateway Status

Source: https://github.com/voyz/ibeam/blob/master/README.md

A command to check if the Interactive Brokers Gateway is running and accessible after IBeam has started. It queries the authentication status endpoint.

```shell
curl -X GET "https://localhost:5000/v1/api/iserver/auth/status" -k
```

--------------------------------

### Run IBeam with Docker Compose

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

Starts the IBeam service in detached mode using Docker Compose, building the image if necessary. This command assumes a 'compose.yaml' and 'env.list' file are present in the current directory.

```shell
docker compose up -d --build
```

--------------------------------

### Docker Compose Configuration for IBeam

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

Defines a Docker Compose setup for running a local IBeam instance. It specifies the build context, container name, environment file, port mapping, network mode, and restart policy.

```yaml
services:
  ibeam:
    build: .
    container_name: ibeam
    env_file:
      - env.list
    ports:
      - 5000:5000
    network_mode: bridge # Required due to clientportal.gw IP whitelist
    restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded
```

--------------------------------

### Restart IBeam Container

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Stops and then starts the IBeam Docker container. This procedure restarts the IBeam application without affecting the host server.

```docker
docker stop ibeam
docker start ibeam
```

--------------------------------

### Example conf.yaml for IBeam Inputs

Source: https://github.com/voyz/ibeam/wiki/Advanced-Secrets

This YAML snippet shows a configuration block for defining IP addresses that the IBeam service should allow or deny access from. It's part of the `conf.yaml` file located within the inputs directory mounted to the service.

```yaml
...
ips:
  allow:
    - 127.0.0.1
  deny:
    - 0-255.*.*.*
```

--------------------------------

### Partial Fill Information Example

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/RealtimeSubscription.md

This JSON snippet details partial fills for a specific order, showing quantities filled, remaining, average price, and final status.

```json
{
  "topic": "sor" ,
  "args": [
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "sizeAndFills": "100/622",
      "remainingQuantity": 622.0,
      "filledQuantity": 100.0,
      "avgPrice": "382.45"
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "sizeAndFills": "700/22",
      "remainingQuantity": 22.0,
      "filledQuantity": 700.0
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "sizeAndFills": "722",
      "orderDesc": "Sold 722 Limit 382.40 GTC",
      "remainingQuantity": 0.0,
      "filledQuantity": 722.0,
      "status": "Filled",
      "timeInForce": "GTC",
      "price": 382.4,
      "bgColor": "#FFFFFF",
      "fgColor": "#000000"
     }
   ]
}
```

--------------------------------

### Verify IBeam Connection Status

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Sends a GET request to the IBeam API's tickle endpoint to verify successful authentication. A successful response indicates the application is running and authenticated.

```APIDOC
curl -X GET "https://localhost:5000/v1/api/tickle" -k

Expected Output for Success:
authenticated:true

Failure Indicators:
- authenticated:false
- Missing 'authenticated' field
- Command fails to execute (e.g., connection refused)
```

--------------------------------

### Docker Run Command for Voyz IBeam with External SMS Handler

Source: https://github.com/voyz/ibeam/wiki/Two-Factor-Authentication

This command starts the Voyz IBeam Docker container, configuring it to use an external SMS handler for two-factor authentication. It specifies the account, password, the URL for the external request handler, and parameters for security.

```shell
docker run --env IBEAM_ACCOUNT=YOUR_PAPER_OR_LIVE_ACCOUNT_ID --env IBEAM_PASSWORD=YOUR_PWD --env IBEAM_TWO_FA_HANDLER=EXTERNAL_REQUEST --env IBEAM_EXTERNAL_REQUEST_URL=https://your-site.com/sms/code --env IBEAM_EXTERNAL_REQUEST_PARAMS={"token":"ANY_STRING_VALUE_FOR_SECURITY"} --env IBEAM_LOG_LEVEL=DEBUG --env IBEAM_PAGE_LOAD_TIMEOUT=500 -p 5000:5000 voyz/ibeam
```

--------------------------------

### Verify IBeam Gateway Configuration via API

Source: https://github.com/voyz/ibeam/wiki/IBeam-Configuration

This `curl` command is used to verify that the IBeam Gateway is correctly configured and accessible on the specified port (8000). It makes a GET request to the /v1/api/one/user endpoint, bypassing SSL certificate verification with the `-k` flag.

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

Description:
  Tests connectivity and configuration of the IBeam Gateway by querying the user API endpoint.

Parameters:
  -X GET: Specifies the HTTP GET method.
  https://localhost:8000/v1/api/one/user: The target URL for the API request, including the custom port.
  -k: Allows insecure connections by skipping certificate validation.

Expected Outcome:
  A successful response from the Gateway API, confirming the port configuration is active.
```

--------------------------------

### Configure Local Host IP Allow List

Source: https://github.com/voyz/ibeam/wiki/Advanced-Secrets

Example configuration snippet for `conf.yaml` showing how to add the Docker gateway IP address to the allowed list for local host access.

```yaml
ips:
  allow:
    - 127.0.0.1
    - 172.18.0.1
  deny:
    - 0-255.*.*.*

```

--------------------------------

### IBeam General Environment Variables

Source: https://github.com/voyz/ibeam/wiki/IBeam-Configuration

Configures general behavior of IBeam, including input/output directories, gateway process matching, logging verbosity, request handling, and session management.

```APIDOC
IBeam General Configuration:

IBEAM_INPUTS_DIR
  Default: /srv/inputs/
  Description: Directory path for inputs.

IBEAM_OUTPUTS_DIR
  Default: ../outputs
  Description: Directory path for outputs.

IBEAM_GATEWAY_DIR
  Default: UNDEFINED
  Description: Path to the root of the IBKR Gateway.

IBEAM_CHROME_DRIVER_PATH
  Default: UNDEFINED
  Description: Path to the Chrome Driver executable file.

IBEAM_GATEWAY_STARTUP
  Default: 20
  Description: Seconds to wait for Gateway to respond after startup.

IBEAM_GATEWAY_PROCESS_MATCH
  Default: ibgroup.web.core.clientportal.gw.GatewayStart
  Description: Gateway process name to match against.

IBEAM_MAINTENANCE_INTERVAL
  Default: 60
  Description: Seconds between each maintenance cycle.

IBEAM_SPAWN_NEW_PROCESSES
  Default: False
  Description: Whether new processes should be spawned for each maintenance.

IBEAM_LOG_LEVEL
  Default: INFO
  Description: Verbosity level of the logger.

IBEAM_LOG_TO_FILE
  Default: True
  Description: Whether logs should also be saved to a file.

IBEAM_LOG_FORMAT
  Default: %(asctime)s|%(levelname)-.1s| %(message)s
  Description: Log format used by IBeam.

IBEAM_REQUEST_RETRIES
  Default: 2
  Description: Number of times to reattempt a request to the gateway.

IBEAM_REQUEST_TIMEOUT
  Default: 15
  Description: Seconds to wait for a request to complete.

IBEAM_RESTART_FAILED_SESSIONS
  Default: True
  Description: Whether Gateway should be restarted on failed sessions.

IBEAM_RESTART_WAIT
  Default: 15
  Description: Seconds to wait for a restart to complete.

IBEAM_REAUTHENTICATE_WAIT
  Default: 15
  Description: Seconds to wait for a reauthentication to complete.

IBEAM_HEALTH_SERVER_PORT
  Default: 5001
  Description: Port to start the health server on.

IBEAM_SECRETS_SOURCE
  Default: env
  Description: Source of secrets (e.g., 'env', 'gcp').

IBEAM_GCP_SECRETS_URL
  Default: None
  Description: Base URL for GCP secrets manager.

IBEAM_START_ACTIVE
  Default: True
  Description: Whether IBeam should start activated or dormant.
```

--------------------------------

### Load Gateway Demo Script

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/root/webapps/demo/index.html

Dynamically writes a script tag to the document to load the gateway demo JavaScript file. This ensures the demo functionality is available.

```javascript
document.write('<script type="text/javascript" src="demo/gateway.demo.js?9343fc8b454b4"></'+'script>');
```

--------------------------------

### Manually Launch IBeam Container

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Directly initiates the IBeam Docker container using `docker run`. This command maps ports, mounts volumes for input/output, and sets environment variables from a file.

```docker
docker run -d --env-file /root/ibeam_files/env.list --name ibeam -p 5000:5000 -v /root/ibeam_files/inputs_directory/:/srv/inputs -v /root/ibeam_files/outputs:/srv/outputs:rw voyz/ibeam:latest
```

--------------------------------

### Question Template for IBeam

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

A template to help users formulate clear questions when seeking help or documentation for IBeam.

```markdown
What are you trying to do or find out more about?

Where have you looked?

Where did you expect to find this information?
```

--------------------------------

### Get Current Day Orders API

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/RealtimeSubscription.md

Retrieves all active orders for the current day. This endpoint is used to fetch a snapshot of all orders currently in the system.

```APIDOC
GET /iserver/account/orders?force=false

Description:
  Retrieves all active orders for the current day.

Parameters:
  force (boolean, optional): If true, forces a refresh of the order data.

Returns:
  JSON object containing a list of current day orders.
```

--------------------------------

### Test IBeam Gateway Endpoint

Source: https://github.com/voyz/ibeam/wiki/Advanced-Secrets

Uses `curl` to send a GET request to the IBeam Gateway API endpoint `/v1/api/one/user` to verify it's running and accessible.

```bash
curl -X GET "https://localhost:5000/v1/api/one/user" -k

```

--------------------------------

### Build and Push Multi-Platform Docker Image

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

Builds a multi-platform Docker image (supporting amd64 and arm64) for IBeam and pushes it to a specified repository. Replace `<repo-username>` and `<tag>` with your actual repository details.

```shell
docker buildx build --platform linux/amd64,linux/arm64 -t <repo-username>/ibeam:<tag> --push .
```

--------------------------------

### Order Status Data Example

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/RealtimeSubscription.md

This JSON snippet represents the status of an order, including account details, order ID, and associated status information with color codes.

```json
{
  "topic": "sor" ,
  "args": [
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "status": "PendingSubmit",
      "fgColor": "#3399CC"
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "status": "PreSubmitted",
      "bgColor": "#FFFFFF",
      "fgColor": "#0000CC"
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "status": "Submitted",
      "bgColor": "#000000",
      "fgColor": "#00F000"
     }
   ]
}
```

--------------------------------

### Market Data (Level I) Streaming Request

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/RealtimeSubscription.md

Example of sending a request to subscribe to Level I market data for a specific contract identifier (conid) and fields via the WebSocket API.

```JavaScript
ws.send('smd+265598+{"fields":["31","83"]}');
```

--------------------------------

### Mounting IBeam Inputs Directory with Docker

Source: https://github.com/voyz/ibeam/wiki/Inputs-And-Outputs

This snippet shows how to mount a local directory containing input files into the IBeam Docker container. This is crucial for providing IBeam with necessary files like configuration or TLS certificates, which can override existing ones. The mounted directory inside the container must correspond to the IBEAM_INPUTS_DIR environment variable.

```posh
docker run -v /host/path/to/inputs:/container/path/to/inputs [OTHER_OPTIONS] voyz/ibeam

```

--------------------------------

### Use PEM Certificate with cURL

Source: https://github.com/voyz/ibeam/wiki/TLS-Certificates-and-HTTPS

Example of how to use a PEM certificate with the cURL command-line tool to make secure HTTPS requests. The `--cacert` flag specifies the path to the CA certificate file.

```APIDOC
cURL Command:
  curl -X GET "https://localhost:5000/v1/api/iserver/auth/status" --cacert cacert.pem

Description:
  This command sends a GET request to the specified URL and uses the `cacert.pem` file for SSL certificate verification.

Parameters:
  -X GET: Specifies the HTTP method as GET.
  "https://localhost:5000/v1/api/iserver/auth/status": The target URL.
  --cacert cacert.pem: Specifies the CA certificate file to use for verification.
```

--------------------------------

### IBeam Gateway Configuration File (`conf.yaml`)

Source: https://github.com/voyz/ibeam/wiki/Gateway-Configuration

This snippet shows the default `conf.yaml` file used by the IBeam Gateway. It defines various parameters such as IP address localization, SSL settings, listening ports, service environment, authentication delays, server options, CORS policies, web application definitions, and IP access control lists (allow/deny).

```yaml
ip2loc: "US"
proxyRemoteSsl: true
proxyRemoteHost: "https://api.ibkr.com"
listenPort: 5000
listenSsl: true
ccp: false
svcEnvironment: "v1"
sslCert: "vertx.jks"
sslPwd: "mywebapi"
authDelay: 3000
portalBaseURL: ""
serverOptions:
  blockedThreadCheckInterval: 1000000
  eventLoopPoolSize: 20
  workerPoolSize: 20
  maxWorkerExecuteTime: 100
  internalBlockingPoolSize: 20
cors:
  origin.allowed: "*"
  allowCredentials: false
webApps:
  - name: "demo"
    index: "index.html"
ips:
  allow:
    - 10.*
    - 192.*
    - 131.216.*
    - 172.17.0.* # docker internal
    - 127.0.0.1 # localhost
    - x.x.x.x # IP address of your machine used to call the API
  deny:
    - 212.90.324.10
    - 0.0.0.0/0 # all other addresses

```

--------------------------------

### Build Single-Platform Docker Image (docker buildx)

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

Builds a Docker image for the IBeam project using 'docker buildx' with the '--load' flag. This command is an alternative to 'docker build' for creating images intended for local use.

```shell
docker buildx build -t ibeam --load .
```

--------------------------------

### Check Running Docker Containers

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Lists all active Docker containers, allowing verification that the IBeam container is running and its status (e.g., 'Up X minutes').

```docker
docker ps
```

--------------------------------

### Test IBeam Gateway API

Source: https://github.com/voyz/ibeam/wiki/Advanced-Secrets

This command uses `curl` to send a GET request to the IBeam Gateway API endpoint `/v1/api/one/user`. It's used to verify that the deployed IBeam service is running and accessible, typically after checking its logs.

```bash
curl -X GET "https://localhost:5000/v1/api/one/user" -k
```

--------------------------------

### IBeam Gateway Communication Timeouts and Retries

Source: https://github.com/voyz/ibeam/wiki/IBeam-Configuration

Details configuration parameters related to Gateway startup and internal communication timeouts and retries. These settings help manage IBeam's interaction with the Gateway, ensuring robustness by defining wait periods and retry attempts for various operational checks.

```APIDOC
IBEAM_GATEWAY_STARTUP:
  Description: Timeout in seconds for IBeam to wait for the Gateway to become ready upon startup. IBeam attempts communication every 1 second until this timeout is reached.
  Default: Not specified in text, but implies a configurable value.

IBEAM_REQUEST_RETRIES:
  Description: Number of times IBeam will retry internal requests to the Gateway (e.g., health, authentication status checks).
  Default: Not specified in text, but implies a configurable value.

IBEAM_REQUEST_TIMEOUT:
  Description: Number of seconds to wait for internal requests to the Gateway to complete before considering them failed and retrying.
  Default: Not specified in text, but implies a configurable value.
```

--------------------------------

### Update IBeam Version

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Updates the IBeam application to a new version by stopping the current container and executing the starter script with the new version tag. It includes steps to confirm the update via logs and container status.

```shell
docker stop ibeam
. starter.sh -t [NEW_VERSION_TAG_HERE]

Example:
. starter.sh -t 0.5.0

After update:
docker ps
# Examine IBeam's logs to ensure successful authentication.
```

--------------------------------

### System Connection Topics

Source: https://github.com/voyz/ibeam/blob/master/copy_cache/clientportal.gw/doc/RealtimeSubscription.md

Handles initial system connection confirmation with username and periodic heartbeats with Unix timestamps.

```json
{
  "topic": "system",
  "success": "user123"
}
{
  "topic": "system",
  "hb": 1594677336001
}
```

--------------------------------

### Node.js Twilio SMS Handler for 2FA

Source: https://github.com/voyz/ibeam/wiki/Two-Factor-Authentication

Provides Node.js Express routes to receive incoming SMS messages from Twilio, parse verification codes, and expose an endpoint to retrieve the latest code. This setup allows IBeam to use external SMS for 2FA without a database.

```javascript
let smsToken;

router.get('/sms/code', async (req, res) => {
    try {
        if(req.query.token != 'ANY_STRING_VALUE_FOR_SECURITY') {
            console.log('Invalid token specified in query param.');
            res.send({});
            return;
        } else {

            console.log('request to /sms/code');

            smsToken = undefined;
            
            let waitCountMax = 120; // seconds
            let waitCount = 0;
            while(waitCount < waitCountMax) {
                waitCount++;
                if(!smsToken) {
                    await new Promise(done => setTimeout(done, 1000));
                } else {
                    break;
                }
            }

            if(smsToken) {
                console.log(`Responding with verificationCode: ${smsToken.verificationCode} obtained at ${smsToken.dateTime}`);
                res.send(smsToken.verificationCode);
                smsToken = undefined;
            } else {
                console.log('No SMS token received.');
                res.send({});
            }
        }
    } catch(e) {
        console.error(e);
        res.send({});
    }
});

router.post('/sms/incoming', async (req, res) => {
    try {
        // "Your requested authentication code: 289026"
        let parts = req.body.Body.split(':');

        if(parts.length == 2) {
            let codePart = parts[1].trim();
            if(parts[0] == 'Your requested authentication code' && codePart.length == 6) {
                console.log(`Parsed Verification Code: ${codePart}`);
                
                
smsToken = { 
                    verificationCode: codePart, 
                    dateTime: (new Date()).toISOString()
                };
                
            } else {
                console.log('Invalid verification code.');
                console.log(JSON.stringify(req.body));
            }
        } else {
            console.log('Non-verification code SMS detected.');
            console.log(JSON.stringify(req.body));
        }
    } catch(e) {
        console.error(e);
    } finally {
        res.writeHead(200, { 'Content-Type': 'text/xml' });
        res.end('<Response />');
    }
});
```

--------------------------------

### IBeam 2FA Configuration

Source: https://github.com/voyz/ibeam/wiki/Two-Factor-Authentication

Environment variables to configure the custom Two-Factor Authentication handler and its behavior within IBeam.

```APIDOC
Environment Variables:

IBEAM_TWO_FA_HANDLER:
  Description: Set to `CUSTOM_HANDLER` to enable the custom 2FA handler.
  Type: string
  Required: No

IBEAM_CUSTOM_TWO_FA_HANDLER:
  Description: The fully qualified name of the custom 2FA handler class (MODULE_NAME.CLASS_NAME).
  Example: `custom_two_fa_handler.CustomTwoFaHandler`
  Type: string
  Required: Yes, if IBEAM_TWO_FA_HANDLER is set to CUSTOM_HANDLER.

IBEAM_STRICT_TWO_FA_CODE:
  Description: Controls whether IBeam strictly enforces 6-digit numeric codes. Set to `False` to disable.
  Type: boolean (string "True"/"False")
  Default: "True"

IBEAM_MAX_FAILED_AUTH:
  Description: Maximum number of consecutive failed authentication attempts before IBeam shuts down to prevent account lock-outs.
  Type: integer
  Default: 10 (or a large number to disable)
```

--------------------------------

### Build Single-Platform Docker Image (docker build)

Source: https://github.com/voyz/ibeam/blob/master/CONTRIBUTING.md

Builds a Docker image for the IBeam project using the standard 'docker build' command. This image is suitable for development and testing on the current machine's platform.

```shell
docker build -t ibeam .
```

--------------------------------

### Monitor IBeam Container Logs

Source: https://github.com/voyz/ibeam/wiki/Cloud-Deployment

Attaches to the IBeam container's logs in real-time, displaying output as it is generated. This is useful for debugging and monitoring the application's status.

```docker
docker logs -f ibeam
```

--------------------------------

### Verify Running Containers

Source: https://github.com/voyz/ibeam/wiki/Advanced-Secrets

Command to list running Docker containers, showing their status, image, ports, and names. Useful for verifying the IBeam service is up.

```powershell
$ docker ps

```

--------------------------------

### IBeam Gateway Route Environment Variables

Source: https://github.com/voyz/ibeam/wiki/IBeam-Configuration

Configures the specific API routes and base URL used for interacting with the IBKR Gateway.

```APIDOC
IBeam Gateway Routes Configuration:

IBEAM_GATEWAY_BASE_URL
  Default: https://localhost:5000
  Description: Base URL of the gateway.

IBEAM_ROUTE_AUTH
  Default: /sso/Login?forwardTo=22&RL=1&ip2loc=on
  Description: Gateway route for authentication page.

IBEAM_ROUTE_VALIDATE
  Default: /v1/portal/sso/validate
  Description: Gateway route for validation call.

IBEAM_ROUTE_REAUTHENTICATE
  Default: /v1/portal/iserver/reauthenticate?force=true
  Description: Gateway route for reauthentication call.

IBEAM_ROUTE_INITIALISE
  Default: /v1/api/iserver/auth/ssodh/init
  Description: Gateway route for session initialisation call.

IBEAM_ROUTE_AUTH_STATUS
  Default: /v1/api/iserver/auth/status
  Description: Gateway route for authentication status call.

IBEAM_ROUTE_TICKLE
  Default: /v1/api/tickle
  Description: Gateway route for tickle call.

IBEAM_ROUTE_LOGOUT
  Default: /v1/api/logout
  Description: Gateway route for logout call.
```