Skip to content

fix: simplify debug handling and remove the 0.0.0.0 default #43574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vmuzikar merged 4 commits into from
Oct 30, 2025
+33 −62
Merged

fix: simplify debug handling and remove the 0.0.0.0 default #43574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d866caa
fix: simplify debug handling and remove the 0.0.0.0 default
shawkins Oct 2, 2025
8b0781f
Update quarkus/dist/src/main/content/bin/kc.sh
shawkins Oct 21, 2025
26cb1a6
removing the ability to specify just the ip
shawkins Oct 21, 2025
79cafe7
Apply suggestions from code review
shawkins Oct 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion quarkus/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ The `kc.sh|bat` script allows you to remotely debug the distribution. For that,
kc.sh --debug start-dev
```

By default, the debug port is available at `8787`. Additionally, you can specify IPv4 or bracketed IPv6 addresses with optional ports, e.g. `--debug 127.0.0.1`, `--debug 127.0.0.1:8786`, `--debug [::1]`, `--debug [::1]:8785`. Make sure to exercise caution when setting IP addresses in the `--debug` parameter, since a value such as `--debug 0.0.0.0:8787` will expose the debug port to all network interfaces!
By default, the debug port is available at `8787` on localhost. Additionally, you can specify IPv4 or bracketed IPv6 addresses with optional ports, e.g. `--debug 127.0.0.1:8786`, `--debug [::1]:8785`. Make sure to exercise caution when setting IP addresses in the `--debug` parameter, since a value such as `--debug 0.0.0.0:8787` will expose the debug port to all network interfaces!

An additional environment variable `DEBUG_SUSPEND` can be set to suspend the JVM, when launched in debug mode. The `DEBUG_SUSPEND` variable supports the following values:

Expand Down
73 changes: 28 additions & 45 deletions quarkus/dist/src/main/content/bin/kc.bat
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,34 @@ if "%OS%" == "Windows_NT" (
set SERVER_OPTS=-Djava.util.logging.manager=org.jboss.logmanager.LogManager -Dquarkus-log-max-startup-records=10000 -Dpicocli.disable.closures=true

set DEBUG_MODE=false
set DEBUG_PORT_VAR=8787
set DEBUG_ADDRESS=0.0.0.0:%DEBUG_PORT_VAR%
set DEBUG_ADDRESS=8787
set DEBUG_SUSPEND_VAR=n
set CONFIG_ARGS=

if NOT "x%KC_DEBUG%" == "x" (
set DEBUG_MODE=%KC_DEBUG%
) else (
if NOT "x%DEBUG%" == "x" (
set DEBUG_MODE=%DEBUG%
)
)

if NOT "x%KC_DEBUG_PORT%" == "x" (
set DEBUG_ADDRESS=%KC_DEBUG_PORT%
) else (
if NOT "x%DEBUG_PORT%" == "x" (
set DEBUG_ADDRESS=%DEBUG_PORT%
)
)

if NOT "x%KC_DEBUG_SUSPEND%" == "x" (
set DEBUG_SUSPEND_VAR=%KC_DEBUG_SUSPEND%
) else (
if NOT "x%DEBUG_SUSPEND%" == "x" (
set DEBUG_SUSPEND_VAR=%DEBUG_SUSPEND%
)
)

rem Read command-line args, the ~ removes the quotes from the parameter
:READ-ARGS
set "KEY=%~1"
Expand All @@ -35,29 +58,15 @@ if "%KEY%" == "" (
)
if "%KEY%" == "--debug" (
set DEBUG_MODE=true
if 1%2 EQU +1%2 (
rem Plain port
set DEBUG_ADDRESS=0.0.0.0:%2
shift
) else (
rem IPv4 or IPv6 address with optional port
(echo %2 | findstr /R "[0-9].*\." >nul || echo %2 | findstr /R "\[.*:.*\]" >nul) && (
(echo %2 | findstr /R "]:[0-9][0-9]*" >nul || echo %2 | findstr /R "^[0-9].*:[0-9][0-9]*" >nul) && (
set DEBUG_ADDRESS=%2
) || (
set DEBUG_ADDRESS=%2:%DEBUG_PORT_VAR%
)
if NOT "x%~2" == "x" (
echo %~2 | findstr /R "^[0-9[]" >nul && (
set DEBUG_ADDRESS=%~2
shift
)
)
shift
goto READ-ARGS
)
if "%KEY%" == "start-dev" (
set CONFIG_ARGS=%CONFIG_ARGS% --profile=dev %KEY%
shift
goto READ-ARGS
)
set "VALUE=%~2"
set PROBABLY_VALUE=false
if "%VALUE%" NEQ "" (
Expand Down Expand Up @@ -140,32 +149,6 @@ if not "x%JAVA_OPTS_APPEND%" == "x" (
set JAVA_OPTS=%JAVA_OPTS% %JAVA_OPTS_APPEND%
)

if NOT "x%KC_DEBUG%" == "x" (
set DEBUG_MODE=%KC_DEBUG%
) else (
if NOT "x%DEBUG%" == "x" (
set DEBUG_MODE=%DEBUG%
)
)

if NOT "x%KC_DEBUG_PORT%" == "x" (
set DEBUG_PORT_VAR=%KC_DEBUG_PORT%
set DEBUG_ADDRESS=0.0.0.0:!DEBUG_PORT_VAR!
) else (
if NOT "x%DEBUG_PORT%" == "x" (
set DEBUG_PORT_VAR=%DEBUG_PORT%
set DEBUG_ADDRESS=0.0.0.0:!DEBUG_PORT_VAR!
)
)

if NOT "x%KC_DEBUG_SUSPEND%" == "x" (
set DEBUG_SUSPEND_VAR=%KC_DEBUG_SUSPEND%
) else (
if NOT "x%DEBUG_SUSPEND%" == "x" (
set DEBUG_SUSPEND_VAR=%DEBUG_SUSPEND%
)
)

rem Set debug settings if not already set
if "%DEBUG_MODE%" == "true" (
echo "%JAVA_OPTS%" | findstr /I "\-agentlib:jdwp" > nul
Expand Down
20 changes: 4 additions & 16 deletions quarkus/dist/src/main/content/bin/kc.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,8 @@ SERVER_OPTS="$SERVER_OPTS -Dquarkus-log-max-startup-records=10000"
CLASSPATH_OPTS="'$(abs_path "../lib/quarkus-run.jar")'"

DEBUG_MODE="${KC_DEBUG:-${DEBUG:-false}}"
DEBUG_PORT="${KC_DEBUG_PORT:-${DEBUG_PORT:-8787}}"
DEBUG_ADDRESS="${KC_DEBUG_PORT:-${DEBUG_PORT:-8787}}"
Copy link
Contributor

@vmuzikar vmuzikar Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should really rely on the default behaviour here with the address. Maybe we could add the explicit 127.0.0.1:8787 as the default instead of just the port?

Copy link
Contributor Author

@shawkins shawkins Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can trust the JRE behavior.

Copy link
Contributor

@vmuzikar vmuzikar Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you see any downsides if we state the address explicitly? Feels safer to me.

Copy link
Contributor Author

@shawkins shawkins Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From what we have documented there wouldn't be a downside to specify localhost:8787. From a jdwp perspective there could eventually be other ways to affect the default address, which this would prevent.

I'm now thinking that adding the handling for specifying the address only, without the port, was a mistake as it will futher deviates from the jdwp handling and adds a little more complexity to our scripts. If there are no objections, I'll remove that with this pr as well.

Copy link
Contributor Author

@shawkins shawkins Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering if we should even rely so much on this kind of debug logic. JAVA_OPTS, JAVA_OPTS_APPEND are perfectly capable of accomodating the options.

https://docs.oracle.com/en/java/javase/21/docs/specs/jpda/conninv.html - it looks like users may want to control virtual thread listing, the allow list if using a publically accessible address, etc. Maybe we should just update the doc to provide an example of using an environment variable.

There is probably even a case to be made for handling -X arguments in the same way we are handling -D.

@keycloak/cloud-native WDYT?

Copy link
Contributor Author

@shawkins shawkins Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vmuzikar are you ok with leaving localhost off, or do you want it on? I can add that, but it will need similar handling as to what was removed for supporting ip only - that is check for a number only after parsing so that it's applied to both the env and the cli cases.

DEBUG_SUSPEND="${KC_DEBUG_SUSPEND:-${DEBUG_SUSPEND:-n}}"
DEBUG_ADDRESS="0.0.0.0:$DEBUG_PORT"

esceval() {
printf '%s\n' "$1" | sed "s/'/'\\\\''/g; 1 s/^/'/; $ s/$/'/"
Expand All @@ -55,20 +54,9 @@ do
case "$1" in
--debug)
DEBUG_MODE=true
if [ -n "$2" ]; then
# Plain port
if echo "$2" | grep -Eq '^[0-9]+$'; then
DEBUG_ADDRESS="0.0.0.0:$2"
shift
# IPv4 or bracketed IPv6 with optional port
elif echo "$2" | grep -Eq '^(([0-9.]+)|(\[[0-9A-Fa-f:]+\]))'; then
if echo "$2" | grep -Eq ':[0-9]+$'; then
DEBUG_ADDRESS="$2"
else
DEBUG_ADDRESS="$2:$DEBUG_PORT"
fi
shift
fi
if echo "$2" | grep -Eq '^([0-9]|\[)'; then
DEBUG_ADDRESS=$2
shift
fi
;;
--)
Expand Down
Loading