# p0 ssh

### 1. Quick health checklist <a href="#id-1-quick-health-checklist" id="id-1-quick-health-checklist"></a>

| Check                  | Command                                                                                                                      | Why it matters                                        |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Node ≥ 20              | `node -v`                                                                                                                    | Older Node versions break npm‑installed CLI binaries. |
| P0 CLI in PATH         | `p0 --version`                                                                                                               | Verifies global install succeeded.                    |
| AWS CLI v2             | `aws --version`                                                                                                              | `ssm start-session` lives here.                       |
| Session Manager plugin | `session-manager-plugin --version`                                                                                           | Required for SSM tunnel on AWS.                       |
| gcloud SDK             | `gcloud --version`                                                                                                           | Provides `start-iap-tunnel`.                          |
| gcloud login           | `gcloud auth list`                                                                                                           | IAP tunnel fails without a valid OAuth token.         |
| P0 identity file       | <p>macOS & Linux:<br><code>cat \~/.p0/identity.json</code><br>Windows:</p><p><code>%USERPROFILE%.p0\identity.json</code></p> | Confirms `p0 login` completed & org slug recorded.    |

***

### 2. Common CLI start‑up errors <a href="#id-2-common-cli-start-up-errors" id="id-2-common-cli-start-up-errors"></a>

| Symptom / Message                                  | Likely cause                                    | Fix & rationale                                                                      |
| -------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------ |
| `node: bad option: --require ts-node/register`     | Node < 20.                                      | Upgrade Node: the CLI is compiled for ESM features included in v20+.                 |
| `Cannot find module '@p0security/cli'`             | CLI not in PATH or NPM global root not in PATH. | Re‑install with `npm i -g @p0security/cli` **and** restart terminal so PATH reloads. |
| `The 'org' argument is required` during `p0 login` | Forgot org slug env var.                        | Run `p0 login <ORG_ID>` or export `P0_ORG`.                                          |

***

### 3 Errors *before* cloud access is granted (P0 layer) <a href="#id-3-errors-before-cloud-access-is-granted" id="id-3-errors-before-cloud-access-is-granted"></a>

| Message                                                             | Cause                                             | Fix                                                                      |
| ------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------ |
| `This organization is not configured for SSH access via the P0 CLI` | Admins haven't installed the **SSH integration**. | Ask platform team to complete P0 onboarding for SSH providers.           |
| `Server did not return a request id`                                | Backend 503 or mis‑shaped request.                | Retry. If persistent, grab CLI logs (`--debug`) and open support ticket. |
| `--approved` exits immediately                                      | Access not pre‑approved.                          | Remove the flag **or** get an approver to pre‑approve via Slack.         |

***

### 4 Errors during *access propagation* (AWS & GCP) <a href="#id-4-errors-during-access-propagation" id="id-4-errors-during-access-propagation"></a>

| Cloud | Error                                                                      | Root reason                                 | Resolution                                                            |
| ----- | -------------------------------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------- |
| AWS   | `AccessDeniedException` OR `is not authorized to perform ssm:StartSession` | IAM policy not yet visible to SSM agent.    | Wait – CLI retries 8 min by default. Use `--debug` to watch attempts. |
| AWS   | `Unable to locate credentials…` inside ProxyCommand                        | Local **AWS CLI** lacks auth (SSO or keys). | `aws sso login --profile <name>`**or** set `AWS_PROFILE`.             |
| GCP   | `Please log in to the gcloud CLI to SSH`                                   | OAuth token expired.                        | `gcloud auth login` again (token TTL 12 h).                           |
| GCP   | Tunnel hangs at 127.0.0.1:0                                                | Firewall denies egress websockets.          | Check corporate proxy, allow `iap.googleapis.com:443`.                |

***

### 5 OpenSSH / Network level failures **after** access granted <a href="#id-5-openssh-network-level-failures-after-access-granted" id="id-5-openssh-network-level-failures-after-access-granted"></a>

| Error / Symptom                                            | Cause                                               | Fix                                                                                               |
| ---------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ssh: connect to host … port 22: Connection refused` (GCP) | SSH daemon disabled or moved.                       | Start `sshd` on VM or revert to port 22. (Azure note: port override unsupported.)                 |
| `Too many authentication failures`                         | Agent offered multiple keys before the P0 temp key. | CLI already adds `IdentitiesOnly=yes`; override your local `ssh_config` or kill `ssh-agent` keys. |
| Port forward fails with `bind: Address already in use`     | Local port occupied.                                | Change **local** part of `-L` or `-R` binding.                                                    |
| Windows PowerShell: arguments split incorrectly            | Quotes not escaped.                                 | Wrap the entire SSH tail in double quotes and escape inner quotes (see examples).                 |

***

### 6 Sudo & privilege issues <a href="#id-6-sudo-and-privilege-issues" id="id-6-sudo-and-privilege-issues"></a>

| Scenario                 | Explanation                                                  | Mitigation                                                       |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------- |
| `sudo: no tty present`   | Your remote command used `sudo` inside non‑interactive mode. | Transpose with `sudo -n <cmd>` **or** request interactive shell. |
| No sudo despite `--sudo` | Approver rejected elevated scope.                            | Check Slack thread, re‑submit with business justification.       |

***

### 7 File‑transfer (SCP) issues <a href="#id-7-file-transfer-scp-issues" id="id-7-file-transfer-scp-issues"></a>

| Error                                | Root cause                             | Fix                                                                            |
| ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------ |
| `scp: protocol error: : Broken pipe` | ProxyCommand died (SSM/IAP restarted). | Large transfers: add `-- -o ServerAliveInterval=60` flag to keep tunnel alive. |

***

### 8 Collecting diagnostics <a href="#id-8-collecting-diagnostics" id="id-8-collecting-diagnostics"></a>

Run with maximum verbosity and pipe logs:

```plaintext
P0_LOG_LEVEL=debug p0 ssh <dest> --provider <cloud> --debug -- -vvv 2>&1 | tee p0-debug.log
```

Upload `p0-debug.log` in your support ticket. It includes:

* CLI version, Node version, OS.
* Full child commands (AWS, gcloud, ssh).
* SSH handshake at `-vvv` level.

**Privacy note**: the log contains **temporary** instance IDs and IPs but **never** the private key material.

***

### 9 Escalate to support <a href="#id-9-escalate-to-support" id="id-9-escalate-to-support"></a>

Please gather:

1. **Command you ran** (with flags).
2. **Terminal output** (use §8).
3. Approximate **UTC timestamp**.
4. **Org slug** and **request ID** (shown in Slack).

Send to <support@p0.dev> or post in **#p0-community** Slack.

***

### 10 Self‑service updates & docs <a href="#id-10-self-service-updates-and-docs" id="id-10-self-service-updates-and-docs"></a>

* **Release notes:** <https://github.com/p0-security/p0cli/releases>
* **Full docs:** <https://docs.p0.dev>
* **Upgrade CLI:** `npm -g update @p0security/cli`

***

### 11 Appendix – Decision tree (plain text) <a href="#id-11-appendix-decision-tree" id="id-11-appendix-decision-tree"></a>

```plaintext
Start
 ├─ Does `p0` command run at all? ── No → Check Node + npm global install.
 │
 ├─ Does CLI create Permission Request? ── No → Check org slug, login, or network.
 │
 ├─ Waiting >8 min at "propagate"? ── Yes → Cloud IAM/OS Login stuck; contact admin.
 │
 ├─ Does SSH handshake start? ── No → ProxyCommand dependency (AWS CLI, gcloud) fails.
 │
 ├─ Shell opens but command fails? ── Yes → Remote OS issue (sshd, sudo), fix on VM.
 │
 └─ Success
```

***

**Now you have a one‑stop shop for resolving P0 SSH headaches – happy debugging!**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.p0.dev/p0-cli/troubleshooting/p0-ssh.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.