diff --git a/README.md b/README.md index c70df74..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). @@ -137,6 +137,107 @@ 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. + +> ⚠️ **Attention:** 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_. + +## 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.