Skip to content

[CF1] ZTIA troubleshooting guide final step #26207

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

Closed
wants to merge 2 commits into from
+93 −45
Closed

[CF1] ZTIA troubleshooting guide final step #26207

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3dc3d3e
[CF1] ZTIA troubleshooting guide final step
deadlypants1973 Oct 31, 2025
6dfbd51
Apply suggestions from code review
deadlypants1973 Nov 5, 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
10 changes: 9 additions & 1 deletion ...tworks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -278,7 +278,7 @@ After you have verified that there are no issues with your tunnel's health, conf

### 3. Confirm user existence on the server

To verify the existence of the end user on the server, run the `id <USERNAME>` command on the server to verify that the end user's username exists. If the username does not exist, you must add the user to the server.
To verify the existence of the UNIX user on the server, run the `id <USERNAME>` command on the server to verify that the UNIX username exists. If the username does not exist, you must add the user to the server.
Copy link
Contributor

@lgmugnier lgmugnier Nov 4, 2025

Choose a reason for hiding this comment

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

We should call it UNIX user because people can also SSH in to Windows machines

Copy link
Contributor

@lgmugnier lgmugnier Nov 4, 2025

Choose a reason for hiding this comment

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

although, I guess that would also be another process, so then my recommendation is just to make it clear that these are instructions for a unix server


If the user exists on the server, debug your `sshd_config` file in the following step.

Expand Down Expand Up @@ -472,3 +472,11 @@ These troubleshooting steps could result in you being locked out of your SSH ser
<Render file="ssh/restart-server" product="cloudflare-one" />

By completing all four troubleshooting steps, you should have resolved any connection issues caused by misconfiguration of the SSH server. If issues persist, [recheck `sshd` logs](/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/#review-your-sshd-logs). The example [`sshd_config` shared above](/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/#review-your-sshd_config-file-for-misconfigurations) enables debug logging and may expose more specific issues.

### 5. Contact support

<Render
file="warp/support-ticket-best-practices"
product="cloudflare-one"
params={{ sshMode: true }}
/>
46 changes: 2 additions & 44 deletions ...e-one/team-and-resources/devices/warp/troubleshooting/troubleshooting-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,48 +471,6 @@ To reset the encryption keys on an end user's desktop:

Resetting the encryption keys forces the WARP client to reestablish its tunnel and retrieve the latest configuration.

## 5. File a support ticket

Effective troubleshooting depends on clear, detailed support tickets. The more context you provide, the faster support can identify and resolve the issue.

To ensure efficient resolution when [contacting support](/support/contacting-cloudflare-support/), include as much relevant detail as possible in your ticket:

<ul>
<li>
<label>
<input type="checkbox" /> Context: Briefly describe the scenario or use case (for example, where the user was, what they were trying to do).
</label>
</li>
<li>
<label>
<input type="checkbox" /> Reproduction steps: Describe the steps you took to reproduce the issue during troubleshhooting.
</label>
</li>
<li>
<label>
<input type="checkbox" /> Timestamps: Be specific and include the exact time and time zone when the issue occurred.
</label>
</li>
<li>
<label>
<input type="checkbox" /> Troubleshooting attempts: Outline any troubleshooting steps or changes already attempted to resolve the issue.
</label>
</li>
<li>
<label>
<input type="checkbox" /> WARP diagnostics logs: Include the WARP diag you downloaded from the dashboard or through the CLI.
</label>
</li>
</ul>

:::danger[Avoid vague ticket descriptions]
Refer to the following example of a vague ticket description:

Ken was on the train and had captive portal issues. `warp-diag` is attached.
:::

:::tip[Include scenario, timestamps, and steps taken to troubleshoot the issue]
Refer to the following example of an ideal ticket description:
## 5. Contact support

Karen was on a train on July 17, 2025, at approximately 1:00 PM Central Time. She attempted to connect to a captive portal but received the following error message in Chrome: `ERR_CONNECTION_RESET`. A warp diag was collected immediately after and is attached.
:::
<Render file="warp/support-ticket-best-practices" product="cloudflare-one" />
82 changes: 82 additions & 0 deletions src/content/partials/cloudflare-one/warp/support-ticket-best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
params:
- sshMode?
---

Effective troubleshooting depends on clear, detailed support tickets. The more context you provide, the faster support can identify and resolve the issue.

To ensure efficient resolution when [contacting support](/support/contacting-cloudflare-support/), include as much relevant detail as possible in your ticket:

<ul>
<li>
<label>
<input type="checkbox" /> Context: Briefly describe the scenario or use case (for example, where the user was, what they were trying to do).
</label>
</li>
<li>
<label>
<input type="checkbox" /> Reproduction steps: Describe the steps you took to reproduce the issue during troubleshhooting.
</label>
</li>
<li>
<label>
<input type="checkbox" /> Timestamps: Be specific and include the exact time and time zone when the issue occurred.
</label>
</li>
<li>
<label>
<input type="checkbox" /> Troubleshooting attempts: Outline any troubleshooting steps or changes already attempted to resolve the issue.
</label>
</li>
{props.sshMode ? (
<>
<li>
<label>
<input type="checkbox" /> <code>sshd</code> debug-level logs: Attach the <code>sshd</code> logs you collected in <a href="/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/#review-your-sshd-logs">step 4: Debug <code>sshd_config</code> file misconfiguration</a>.
</label>
</li>
<li>
<label>
<input type="checkbox" /> <code>sshd_config</code> file: Include a copy of your server's <code>sshd_config</code> to help identify any misconfigurations or conflicting directives.
</label>
</li>
<li>
<label>
<input type="checkbox" /> Client-side SSH output: Run the failing SSH command with verbose flags (<code>-vvv</code>) and include the full terminal output to show connection and authentication attempts from the client side.
</label>
</li>
</>
) : (
<li>
<label>
<input type="checkbox" /> WARP diagnostics logs: Include the WARP diag you downloaded from the dashboard or through the CLI.
</label>
</li>
)}
</ul>

:::danger[Avoid vague ticket descriptions]
Refer to the following example of a vague ticket description:

{props.sshMode ? (
<p>User cannot connect to SSH. The tunnel looks fine. Please help.</p>
) : (
<p>Ken was on the train and had captive portal issues. <code>warp-diag</code> is attached.</p>
)}
:::

:::tip[Include scenario, timestamps, and steps taken to troubleshoot the issue]
Refer to the following example of an ideal ticket description:

{props.sshMode ? (
<>
<p>On October 30, 2025, at approximately 3:45 PM UTC, Alice attempted to SSH into 10.116.0.3 (target hostname: prod-db-01) using Access for Infrastructure. The SSH client returned <code>Permission denied (publickey)</code> despite her email being included in the Access policy.</p>
Copy link
Contributor

@lgmugnier lgmugnier Nov 4, 2025

Choose a reason for hiding this comment

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

The most likely error is "Permission denied (none)"


<p>The <code>sshd</code> logs (captured with LogLevel DEBUG3) are attached and show the connection reaching the server but failing at the certificate validation step. The user exists on the server (<code>id alice</code> verified).</p>

<p>The <code>sshd_config</code> file and <code>ssh -vvv [email protected]</code> output are attached. The tunnel status is Healthy in the Cloudflare dashboard, and Access authentication logs show a successful <code>Access granted</code> decision.</p>
</>
) : (
<p>Karen was on a train on July 17, 2025, at approximately 1:00 PM Central Time. She attempted to connect to a captive portal but received the following error message in Chrome: <code>ERR_CONNECTION_RESET</code>. A warp diag was collected immediately after and is attached.</p>
)}
:::