From b5274e22e19665cccabe0e20e83ae487d6ad80a4 Mon Sep 17 00:00:00 2001 From: Faur Ioan-Aurel Date: Fri, 16 May 2025 22:06:56 +0300 Subject: [PATCH 1/5] doc: debugging and reporting issues Document how to configure the debug level before reporting any Coder plugin issue and also how to collect or view the Toolbox log files --- README.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/README.md b/README.md index c70df74..a43fb34 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,42 @@ mitmproxy can do HTTP and SOCKS5 proxying. To configure one or the other: 5. Before authenticating to the Coder deployment we need to tell the plugin where can we find mitmproxy certificates. In Coder's Settings page, set the `TLS CA path` to `~/.mitmproxy/mitmproxy-ca-cert.pem` +## Debugging and Reporting issues + +Enabling debug logging is essential for diagnosing issues with the Toolbox plugin, especially when SSH +connections to the remote environment fail — it provides detailed output that includes SSH negotiation +and command execution, which is not visible at the default log level. + +If you encounter a problem with Coder's JetBrains Toolbox plugin, follow the steps below to gather more +information and help us diagnose and resolve it quickly. + +### Enable Debug Logging 🔍 + +To help with troubleshooting or to gain more insight into the behavior of the plugin and the SSH connection to +the workspace, you can increase the log level to _DEBUG_. + +Steps to Enable Debug Logging: + +1. Open Toolbox + +2. Navigate to the Toolbox App Menu (hexagonal menu icon) > Settings > Advanced. + +3. In the screen that appears, select _DEBUG_ for the `Log level:` section. + +4. Hit the back button at the top. + +There is no need to restart Toolbox, as it will begin logging at the DEBUG level right away. + +⚠️ Toolbox does not persist log level configuration between restarts. + +#### Viewing the Logs + +Once enabled, debug logs will be written to the Toolbox log files. You can access logs directly +via Toolbox App Menu > About > Show log files. + +Alternatively, you can generate a ZIP file using the Workspace Action Menu, available either on the main +Workspaces page in Coder or within the individual workspace view, under the option labeled _Collect logs_. + ## Releasing 1. Check that the changelog lists all the important changes. From 24ac08b8dbfda3e082caa95dae0ef0af3f8091ea Mon Sep 17 00:00:00 2001 From: Faur Ioan-Aurel Date: Fri, 16 May 2025 22:13:14 +0300 Subject: [PATCH 2/5] fix: use github flavored markdown for attention notes --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a43fb34..95b8a0f 100644 --- a/README.md +++ b/README.md @@ -163,7 +163,7 @@ Steps to Enable Debug Logging: There is no need to restart Toolbox, as it will begin logging at the DEBUG level right away. -⚠️ Toolbox does not persist log level configuration between restarts. +> ⚠️ **Attention:** Toolbox does not persist log level configuration between restarts. #### Viewing the Logs From 0cb91ae427b20cfcf78fb860baa023c2faf0c991 Mon Sep 17 00:00:00 2001 From: Faur Ioan-Aurel Date: Sat, 17 May 2025 00:23:01 +0300 Subject: [PATCH 3/5] doc: the settings page and the available options --- README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 95b8a0f..85ce557 100644 --- a/README.md +++ b/README.md @@ -170,9 +170,74 @@ There is no need to restart Toolbox, as it will begin logging at the DEBUG level Once enabled, debug logs will be written to the Toolbox log files. You can access logs directly via Toolbox App Menu > About > Show log files. -Alternatively, you can generate a ZIP file using the Workspace Action Menu, available either on the main +Alternatively, you can generate a ZIP file using the Workspace action menu, available either on the main Workspaces page in Coder or within the individual workspace view, under the option labeled _Collect logs_. +## Coder Settings + +The Coder Settings allows users to control CLI download behavior, SSH configuration, TLS parameters, and data +storage paths. The options can be configured from the plugin's main Workspaces page > deployment action menu > Settings. + +### CLI related settings + +```Binary source``` specifies the source URL or relative path from which the Coder CLI should be downloaded. +If a relative path is provided, it is resolved against the deployment domain. + +```Enable downloads``` allows automatic downloading of the CLI if the current version is missing or outdated. + +```Binary directory``` specifies the directory where CLI binaries are stored. If omitted, it defaults to the data directory. + +```Enable binary directory fallback``` if enabled, falls back to the data directory when the specified binary +directory is not writable. + +```Data directory``` directory where plugin-specific data such as session tokens and binaries are stored if not +overridden by the binary directory setting. + +```Header command``` command that outputs additional HTTP headers. Each line of output must be in the format key=value. +The environment variable CODER_URL will be available to the command process. + +### TLS settings + +The following options control the secure communication behavior of the plugin with Coder deployment and its available API. + +```TLS cert path``` path to a client certificate file for TLS authentication with Coder deployment. +The certificate should be in X.509 PEM format. + +```TLS key path``` path to the private key corresponding to the TLS certificate from above. +The certificate should be in X.509 PEM format. + +```TLS CA path``` the path of a file containing certificates for an alternate certificate authority used to verify TLS +certs returned by the Coder deployment. The file should be in X.509 PEM format. This option can also be used to verify +proxy certificates. + +```TLS alternate hostname``` overrides the hostname used in TLS verification. This is useful when the hostname +used to connect to the Coder deployment does not match the hostname in the TLS certificate. + +### SSH settings + +The following options control the SSH behavior of the Coder CLI. + +```Disable autostart``` adds the --disable-autostart flag to the SSH proxy command, preventing the CLI from keeping +workspaces constantly active. + +```Enable SSH wildcard config``` enables or disables wildcard entries in the SSH configuration, which allow generic +rules for matching multiple workspaces. + +```SSH proxy log directory``` directory where SSH proxy logs are written. Useful for debugging SSH connection issues. + +```SSH network metrics directory``` directory where network information used by the SSH proxy is stored. + +```Extra SSH options``` additional options appended to the SSH configuration. Can be used to customize the behavior of SSH connections. + +### Saving Changes + +Changes made in the settings page are saved by clicking the Save button. Some changes, like toggling SSH wildcard support, +may trigger regeneration of SSH configurations. + +### Security considerations + +> ⚠️ **Attention:** Token authentication is required when TLS certificates are not configured. + ## Releasing 1. Check that the changelog lists all the important changes. From 3246215bf85f64e8af02fa697f41c8c146c8ac36 Mon Sep 17 00:00:00 2001 From: Faur Ioan-Aurel Date: Sat, 17 May 2025 00:28:06 +0300 Subject: [PATCH 4/5] fix: typos --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 85ce557..ddc8fbf 100644 --- a/README.md +++ b/README.md @@ -146,12 +146,12 @@ and command execution, which is not visible at the default log level. If you encounter a problem with Coder's JetBrains Toolbox plugin, follow the steps below to gather more information and help us diagnose and resolve it quickly. -### Enable Debug Logging 🔍 +### Enable Debug Logging To help with troubleshooting or to gain more insight into the behavior of the plugin and the SSH connection to the workspace, you can increase the log level to _DEBUG_. -Steps to Enable Debug Logging: +Steps to enable debug logging: 1. Open Toolbox @@ -161,7 +161,7 @@ Steps to Enable Debug Logging: 4. Hit the back button at the top. -There is no need to restart Toolbox, as it will begin logging at the DEBUG level right away. +There is no need to restart Toolbox, as it will begin logging at the __DEBUG__ level right away. > ⚠️ **Attention:** Toolbox does not persist log level configuration between restarts. From da2981299951af664672abfe35653fdd348a7d21 Mon Sep 17 00:00:00 2001 From: Faur Ioan-Aurel Date: Tue, 20 May 2025 22:02:08 +0300 Subject: [PATCH 5/5] chore: update the minimum required version for TBX --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ddc8fbf..2b749e3 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Connects your JetBrains IDE to Coder workspaces To install this plugin using JetBrains Toolbox, follow the steps below. -1. Install [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/). Make sure it's the `2.6.0.40284` release or +1. Install [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/). Make sure it's the `2.6.0.40632` release or above. 2. Launch the Toolbox app and sign in with your JetBrains account (if needed).