Getting Started¶

How It Works¶

The Session Manager continuously monitors the BotCity Orchestrator task queue in real time. It is responsible for activating resources whenever there are pending tasks and deactivating them when execution finishes and there are no more tasks in the queue.

It is optimized to provide timely resource allocation, ensuring resource availability when needed. This reduces both the idle time of tasks waiting in the BotCity Orchestrator and the idle time of active Runners without tasks to execute.

Process Flow:

Monitor Queue: Session Manager continuously monitors the BotCity Orchestrator task queue.
Resource Activation: When task demand exists, resources are activated to handle the load.
Resource Deactivation: As demand subsides, resources are released and deactivated, reducing costs.

Key Concepts¶

Before diving into the configuration it is important to understand some key concepts which will be referred to below:

host: A host is a computer or virtual machine (locally or in the cloud) that will have its session controlled, this machine must have the BotCity SDK resources installed.
protocol: The protocol to be used for the Session Manager to connect and communicate with the host. Check the list of supported protocols.

Supported Protocols¶

Currently, two protocols are supported:

RDP
AWS EC2 + RDP

RDP - Remote Desktop¶

To set up a host with Remote Desktop support you will need the following information:

Hostname or IP Address: to communicate with the host.
Username: for the session to be launched.
Password: for the user session to be launched.

AWS EC2 + RDP¶

This protocol allows you to not only establish the RDP connection with the host but also manipulate the AWS EC2 instance state by starting and stopping it based on the demand from the BotCity Orchestrator Task queue.

To set up a host with AWS EC2 support you will need the following information:

Instance ID
AWS Region: (Optional) the AWS region where this instance is located.
AWS Access Key ID: (Optional) the AWS API Access Key.
AWS Secret Access Key ID: (Optional) the AWS Secret Access Key.
Hostname or IP Address: to communicate with the host.
Username: for the session to be launched.
Password: for the user session to be launched.

AWS Credentials

The usage of AWS Credentials file is also supported. Make sure to reply Yes during the host add command when asked.

If you use the credentials file, the Region, Access Key and Secret Access Key will not be asked.

Azure VM + RDP¶

This protocol allows configuring an Azure VM to operate by managing the VM state and establishing the RDP connection, starting and stopping it based on the demand from the BotCity Orchestrator Task queue.

It provides two options for authentication when accessing Azure resources:

Using Client Secrets — providing Tenant ID, Client ID, and Client Secret from Azure AD for explicit access
Using Managed Identity — utilizing the VM's managed identity for automatic access without needing to supply secrets

To configure the host to use an Azure VM, you need to provide the following information:

VM Name where the configuration will be applied
Resource Group of the VM in Azure
Subscription ID related to the VM
Tenant ID (Optional) identifies the Azure Active Directory (Azure AD) tenant to which the application belongs
Client ID (Optional) uniquely identifies the application registered in Azure AD
Client Secret (Optional) is the password or secret key associated with the registered application used for secure authentication

Tip

In Azure VM authentication, there are three main ways to provide credentials:

Client Secrets:
Use Tenant ID, Client ID, and Client Secret when you want to explicitly authenticate via a registered application in Azure AD.
This is useful in environments without Managed Identity enabled or for scenarios requiring specific credentials.
Managed Identity:
When the VM has Managed Identity enabled, authentication is done automatically without needing to provide explicit credentials.
This is the most secure and recommended method for applications running on Azure VMs.
Default configuration file (Azure CLI / Environment Variables):
If you have Azure CLI installed and authenticated on the machine, or set environment variables AZURE_TENANT_ID, AZURE_CLIENT_ID, and AZURE_CLIENT_SECRET, you can use these configurations automatically.
This avoids the need to manually pass credentials in the code.

Requirements¶

The Session Manager can run on a dedicated server to maintain constant communication with the BotCity Orchestrator.

For proper communication, the Session Manager server must:

Be able to communicate with the BotCity Orchestrator via HTTPS (Port 443).
Be able to reach the hosts via the network to manage sessions.
Have a user authorized to establish an RDP connection or other necessary connection with the hosts.

Environment Configuration Suggestion

For an environment dedicated solely to running the Session Manager:

OS: Linux
RAM: 2GB

Pay attention to possible adjustments in requirements related to network communication or other resources you may wish to add.

Installation¶

Session Manager is part of the BotCity Studio SDK.

In order to obtain the Session Manager please proceed with the installation described in the getting started guide.

Runner Installation

When installing the SDK exclusively for Session Manager usage, it is not necessary to configure a Runner in this installation.

Installing as a Windows Service

You can install the BotCity Session Manager as a Windows Service following the instructions below:

Tip

You will a Windows OS with Administrative privileges.

Step 1: Create the Service

Open Command Prompt as Administrator:
- Press Win + X and select Command Prompt (Admin) or Windows PowerShell (Admin).
Run the following command to create a new service:
```
sc create SessionManagerService binPath="C:\path\to\your\executable.exe service"
```
- Replace C:\path\to\your\SessionManager.exe with the full path to your .exe file.
- Note: Ensure there is no space between binPath= and the path.

Step 2: Set the Service to Start Automatically

Run the following command to set the service to start automatically on system boot:
```
sc config SessionManagerService start=auto
```
To start the service immediately, use:
```
sc start SessionManagerService
```

Step 3: Verify the Service

Open Services (press Win + R, type services.msc, and press Enter).
Locate SessionManagerService in the list of services to confirm it appears.
Check that the service’s Startup type is set to Automatic.
Reboot the system to verify that the service starts automatically on boot.

Step 4: Testing and Troubleshooting

To check the status of your service, you can use:
```
sc query SessionManagerService
```
If the service does not start, check the log_sm.txt in the logs folder of the BotCity Studio SDK.
Alternatively, check the Event Viewer for errors under Windows Logs > Application.

Uninstalling the Service

To remove the service, run:

sc delete SessionManagerService

This command deletes the service entirely.

Configuration¶

All Session Manager configuration is performed via the Session Manager command line interface (CLI) and saved in the config_file.smdb file (by default in the conf/ folder of the installation).

In order to execute the Session Manager you will need to at least:

Add a host
Attach a runner to a registered host

Customize Database Location

You can customize the location of your Session Manager configuration database by setting the full path to the smdb file in your conf/conf.bcf under the sessionManagerDBPath.

sessionManagerDBPath=/path/example/BotCity/config_file.smdb

Commands¶

Here is a list of available commands for configuring the Session Manager. Click on the desired command for more details.

host - add, edit, remove ¶

Commands for configuring hosts in the Session Manager.

runner - attach, edit, release ¶

Commands for configuring runners in the Session Manager.

list - all ¶

Command to list the configurations made in the Session Manager.

run - local ¶

Command to run the Session Manager.