API to list console sessions #11016

bernardodemarco · 2025-06-12T15:37:30Z

Description

Currently, details about console sessions are stored in the cloud.console_session table in the database. Operators can only access this information by querying the database directly, while end users have no way to view console session data at all.

To address this, this PR proposes to create the listConsoleSessions API. It allows listing the console sessions, with optional filters by domain, account, user, host, instance, IP address, and date. The API is accessible to all account types and, thus, performs proper access validation on the queried resources.

The API supports the following parameters:

Parameter	Description	Required
`id`	Console session ID.	No
`activeonly`	Indicates whether only currently active console sessions should be listed. Defaults to `true`. Active sessions are the ones that have been acquired and have not been removed.	No
`isrecursive`	Lists console sessions recursively per domain. Defaults to `false`.	No
`clientaddress`	IP address of the client that accessed the console.	No
`consoleendpointcreatoraddress`	IP address of the client that generated the console session endpoint.	No
`hostid`	ID of the host where the VM was running when the console session endpoint was generated. Only available for Root Admins.	No
`instanceid`	ID of the VM associated with the console session.	No
`startdate`	If provided, only console sessions that were acquired from this date onward will be listed.	No
`enddate`	If provided, only console sessions that were acquired up to this date will be listed.	No
`domainid`	Domain ID of the account that generated the console session endpoint.	No
`accountid`	ID of the account that generated the console session endpoint.	No
`userid`	ID of the user that generated the console session endpoint.	No
`page`	Used for pagination along with `pagesize`.	No
`pagesize`	User for pagination along with `page`.	No

This PR only encompasses the creation of the API listConsoleSessions API. UI support will be implemented in a future PR.

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
build/CI
test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Screenshots (if appropriate):

How Has This Been Tested?

Tests Setup

Created the following domain hierarchy:

ROOT
├── d1
│   └── d1-d1
└── d2

Created the following accounts:

Name	Role Type	Domain
admin	Admin	ROOT
u1	User	ROOT
d1-admin	DomainAdmin	ROOT/d1
d1-user	User	ROOT/d1
d1-d1-admin	DomainAdmin	ROOT/d1/d1-d1
d1-d1-user	User	ROOT/d1/d1-d1
d2-admin	DomainAdmin	ROOT/d2

Deployed a VM for each account:

ID	Name	Instance Name	Account Name
5	v-5-VM	v-5-VM	system
6	s-6-VM	s-6-VM	system
7	VM-fb5fa7ab-c5a0-4943-88bd-dedec9007c7b	i-7-7-VM	d1-d1-user
8	r-8-VM	r-8-VM	d1-d1-user
9	VM-16febbcd-a35e-4f05-87d3-1a27db077136	i-6-9-VM	d1-user
10	r-10-VM	r-10-VM	d1-user
11	VM-d3208889-d3fd-43fe-9087-3cf5d863a3b1	i-4-11-VM	d1-admin
12	r-12-VM	r-12-VM	d1-admin
13	VM-dea9f800-afd0-4054-9160-3a676a0df3d3	i-2-13-VM	admin
14	r-14-VM	r-14-VM	admin
15	VM-766b6485-330e-4ec9-9516-59e17b52c1c7	i-8-15-VM	u1
16	r-16-VM	r-16-VM	u1
17	VM-d2d7ded1-e210-4191-9a0e-75c3914de043	i-9-17-VM	d2-admin
18	r-18-VM	r-18-VM	d2-admin
19	VM-266b73ff-2684-46b9-b36e-830ac83c5c14	i-5-19-VM	d1-d1-admin
20	r-20-VM	r-20-VM	d1-d1-admin

With each account, I accessed all available VM consoles through the CPVM.

`listConsoleSessions` tests

With the admin account, verified that the API lists console sessions correctly according to the specified parameters
With the u1 account, verified that it is only possible to access the account's console sessions
With the d2-admin account, verified that it is only possible to list the console sessions of the d2 domain
With the d1-admin account, verified that it is only possible to list the console sessions of the d1 and d1/d1-d1 domains
With the d1-user account, verified that it is only possible to list the d1-user console sessions
With the d1-d1-admin account, verified that it is only possible to list the console sessions of the d1/d1-d1 domain
With the d1-d1-user account, verified that it is only possible to list the d1-d1-user console sessions
With accounts of the User type, verified that the hostid parameter is not considered in the API workflow
With accounts of the User type, verified that the hostid and hostname response attributes are not included in the API's return

bernardodemarco · 2025-06-12T15:38:23Z

@blueorangutan package

codecov · 2025-06-12T15:45:16Z

Codecov Report

Attention: Patch coverage is 54.67626% with 126 lines in your changes missing coverage. Please review.

Project coverage is 16.59%. Comparing base (0bd35a5) to head (758bdae).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...loudstack/api/response/ConsoleSessionResponse.java	50.51%	48 Missing ⚠️
...n/java/com/cloud/vm/dao/ConsoleSessionDaoImpl.java	0.00%	37 Missing ⚠️
...mand/user/consoleproxy/ListConsoleSessionsCmd.java	52.63%	27 Missing ⚠️
...a/src/main/java/com/cloud/vm/ConsoleSessionVO.java	14.28%	6 Missing ⚠️
...udstack/consoleproxy/ConsoleAccessManagerImpl.java	87.50%	5 Missing and 1 partial ⚠️
...src/main/java/com/cloud/api/ApiResponseHelper.java	96.77%	0 Missing and 1 partial ⚠️
...in/java/com/cloud/server/ManagementServerImpl.java	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #11016      +/-   ##
============================================
+ Coverage     16.57%   16.59%   +0.02%     
- Complexity    13968    13997      +29     
============================================
  Files          5743     5745       +2     
  Lines        510470   510769     +299     
  Branches      62074    62091      +17     
============================================
+ Hits          84615    84785     +170     
- Misses       416393   416518     +125     
- Partials       9462     9466       +4

Flag	Coverage Δ
uitests	`3.90% <ø> (ø)`
unittests	`17.49% <54.67%> (+0.02%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

bernardodemarco · 2025-06-12T18:02:52Z

@blueorangutan package

blueorangutan · 2025-06-12T18:04:03Z

@bernardodemarco a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2025-06-12T19:05:38Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 13755

bernardodemarco · 2025-06-13T18:26:30Z

@blueorangutan package

blueorangutan · 2025-06-13T18:28:06Z

@bernardodemarco a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

DaanHoogland

clgtm, only doubt, is the active parameter needed? would we ever want to list no longer available sessions?

blueorangutan · 2025-06-13T18:54:26Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 13766

blueorangutan · 2025-06-13T19:37:33Z

Packaging result [SF]: ✖️ el8 ✖️ el9 ✖️ debian ✖️ suse15. SL-JID 13771

bernardodemarco · 2025-06-13T21:50:46Z

@DaanHoogland, thanks for the review!

is the active parameter needed? would we ever want to list no longer available sessions?

Yes, listing removed sessions is useful for audit and analysis purposes, as it allows users to track who generated a console endpoint, who accessed it, and when it was generated, acquired, and removed. Listing only active sessions, on the other hand, is helpful for verifying whether someone is currently using a VM.

blueorangutan · 2025-06-14T10:37:50Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 13777

DaanHoogland · 2025-06-14T19:12:34Z

@blueorangutan test

blueorangutan · 2025-06-14T19:14:03Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + kvm-ol8) has been kicked to run smoke tests

blueorangutan · 2025-06-15T11:19:33Z

[SF] Trillian test result (tid-13527)
Environment: kvm-ol8 (x2), Advanced Networking with Mgmt server ol8
Total time taken: 54933 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr11016-t13527-kvm-ol8.zip
Smoke tests completed. 141 look OK, 0 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File

DaanHoogland · 2025-06-16T07:12:15Z

@blueorangutan test ol8 vmware-70u3 keepEnv

blueorangutan · 2025-06-16T07:14:04Z

@DaanHoogland a [SL] Trillian-Jenkins test job (ol8 mgmt + vmware-70u3) has been kicked to run smoke tests

blueorangutan · 2025-06-17T01:53:09Z

[SF] Trillian test result (tid-13531)
Environment: vmware-70u3 (x2), Advanced Networking with Mgmt server ol8
Total time taken: 64089 seconds
Marvin logs: https://github.com/blueorangutan/acs-prs/releases/download/trillian/pr11016-t13531-vmware-70u3.zip
Smoke tests completed. 140 look OK, 1 have errors, 0 did not run
Only failed and skipped tests results shown below:

Test	Result	Time (s)	Test File
test_01_prepare_and_cancel_maintenance	`Error`	0.23	test_ms_maintenance_and_safe_shutdown.py

DaanHoogland

clgtm

bernardodemarco · 2025-06-24T12:02:45Z

@blueorangutan package

blueorangutan · 2025-06-24T12:04:04Z

@bernardodemarco a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

DaanHoogland · 2025-06-24T12:19:45Z

@blueorangutan package

blueorangutan · 2025-06-24T12:22:03Z

@DaanHoogland a [SL] Jenkins job has been kicked to build packages. It will be bundled with KVM, XenServer and VMware SystemVM templates. I'll keep you posted as I make progress.

blueorangutan · 2025-06-24T12:59:36Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✖️ debian ✔️ suse15. SL-JID 13897

...rc/main/java/org/apache/cloudstack/api/command/user/consoleproxy/ListConsoleSessionsCmd.java

nvazquez · 2025-06-24T13:22:13Z

server/src/main/java/com/cloud/api/ApiResponseHelper.java

+        Domain domain = ApiDBUtils.findDomainById(consoleSession.getDomainId());
+        if (domain != null) {
+            consoleSessionResponse.setDomain(domain.getName());
+            consoleSessionResponse.setDomainPath(domain.getPath());
+            consoleSessionResponse.setDomainId(domain.getUuid());
+        }


Can this be extracted to a new method which also checks for NPE on consoleSession? Same for user, account and host setters below

server/src/main/java/org/apache/cloudstack/consoleproxy/ConsoleAccessManagerImpl.java

blueorangutan · 2025-06-24T13:44:17Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ debian ✔️ suse15. SL-JID 13898

DaanHoogland · 2025-06-24T13:54:40Z

@blueorangutan test ol8 vmware-70u3 keepEnv

…leproxy/ListConsoleSessionsCmd.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

…eAccessManagerImpl.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

nvazquez · 2025-06-24T14:06:01Z

Hi @bernardodemarco thanks for the feature! I'll try to test it soon

bernardodemarco · 2025-06-24T14:09:22Z

Hi @bernardodemarco thanks for the feature! I'll try to test it soon

@nvazquez okay, many thanks for the review! I'll apply this suggestion #11016 (comment) ASAP

boring-cyborg bot added component:api component:management-server Python Warning... Python code Ahead! labels Jun 12, 2025

bernardodemarco added this to the 4.21.0 milestone Jun 12, 2025

bernardodemarco requested review from weizhouapache, nvazquez, sureshanaparti, winterhazel and JoaoJandre and removed request for weizhouapache June 12, 2025 15:37

bernardodemarco requested a review from DaanHoogland June 12, 2025 15:38

bernardodemarco force-pushed the listconsolesessions branch from 79f6d2d to ad7af57 Compare June 13, 2025 18:26

DaanHoogland reviewed Jun 13, 2025

View reviewed changes

DaanHoogland added the status:needs-testing label Jun 17, 2025

DaanHoogland approved these changes Jun 17, 2025

View reviewed changes

bernardodemarco added 7 commits June 24, 2025 09:01

create API to list console sessions

71f7c8a

add listConsoleSessions API to list of MS APIs

3c62f66

persist console endpoint creator domain ID

dae0395

fix invalid access validation performed to the domainId attribute

470211b

deal with inexistent provided domain ID

1d4626d

add end of line to ListConsoleSessionsCmd.java

39df679

enhance access control validation

3e28b99

bernardodemarco force-pushed the listconsolesessions branch from ad7af57 to 3e28b99 Compare June 24, 2025 12:02

nvazquez reviewed Jun 24, 2025

View reviewed changes

bernardodemarco and others added 2 commits June 24, 2025 10:55

Update api/src/main/java/org/apache/cloudstack/api/command/user/conso…

adf302a

…leproxy/ListConsoleSessionsCmd.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

Update server/src/main/java/org/apache/cloudstack/consoleproxy/Consol…

758bdae

…eAccessManagerImpl.java Co-authored-by: Nicolas Vazquez <nicovazquez90@gmail.com>

API to list console sessions #11016

Are you sure you want to change the base?

API to list console sessions #11016

Uh oh!

Conversation

bernardodemarco commented Jun 12, 2025

Description

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Screenshots (if appropriate):

How Has This Been Tested?

Tests Setup

listConsoleSessions tests

Uh oh!

bernardodemarco commented Jun 12, 2025

Uh oh!

codecov bot commented Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

bernardodemarco commented Jun 12, 2025

Uh oh!

blueorangutan commented Jun 12, 2025

Uh oh!

blueorangutan commented Jun 12, 2025

Uh oh!

bernardodemarco commented Jun 13, 2025

Uh oh!

blueorangutan commented Jun 13, 2025

Uh oh!

DaanHoogland left a comment

Choose a reason for hiding this comment

Uh oh!

blueorangutan commented Jun 13, 2025

Uh oh!

blueorangutan commented Jun 13, 2025

Uh oh!

bernardodemarco commented Jun 13, 2025

Uh oh!

blueorangutan commented Jun 14, 2025

Uh oh!

DaanHoogland commented Jun 14, 2025

Uh oh!

blueorangutan commented Jun 14, 2025

Uh oh!

blueorangutan commented Jun 15, 2025

Uh oh!

DaanHoogland commented Jun 16, 2025

Uh oh!

blueorangutan commented Jun 16, 2025

Uh oh!

blueorangutan commented Jun 17, 2025

Uh oh!

DaanHoogland left a comment

Choose a reason for hiding this comment

Uh oh!

bernardodemarco commented Jun 24, 2025

Uh oh!

blueorangutan commented Jun 24, 2025

Uh oh!

DaanHoogland commented Jun 24, 2025

Uh oh!

blueorangutan commented Jun 24, 2025

Uh oh!

blueorangutan commented Jun 24, 2025

Uh oh!

Uh oh!

nvazquez Jun 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

blueorangutan commented Jun 24, 2025

Uh oh!

DaanHoogland commented Jun 24, 2025

Uh oh!

nvazquez commented Jun 24, 2025

Uh oh!

bernardodemarco commented Jun 24, 2025

Uh oh!

`listConsoleSessions` tests

codecov bot commented Jun 12, 2025 •

edited

Loading