> For the complete documentation index, see [llms.txt](https://documentation.2pintsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.2pintsoftware.com/ipxe-ws/4.0/troubleshooting/ipxe-boot-diagnostics.md).

# iPXE Boot Diagnostics

### Getting to an iPXE console session

When things fail early in the process, you can get to a console and try to troubleshoot. Before the initial 2Pint Software splash screen appears, press the **C** key on your keyboard. There is only a small window of time to press it, so keep pressing it until the console appears. Press the **C** key when the following is visible or about to appear:

![You can press 'C' multiple times, so keep pressing it until the screen below is shown.](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/V4P9ol7ELOEIBe3scqGp/image.png)

Once at the console, type `help` to get a list of commands available for custom troubleshooting. The machine is now in debug mode, and typing `exit` continues the regular process, step by step, stopping at each command.

![An iPXE boot stopped at the troubleshooting part.](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/EzVvB3AlVipsvO3BfM6p/image.png)

2Pint Software support staff might give you specific sequences of commands to run. Otherwise, if you are just doing an initial test, type `exit` and press Enter, as shown below:

![](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/6aoXlrFs5P44vN4vjkVf/image.png)

![The next command or sequence is shown on screen with its value. In this case, the screen will be cleared.](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/CIUBPRMHhnv1lUDptkEL/image.png)

![](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/p68A4xb7g1uZ98smhr4X/image.png)

Each time you type `exit` and press Enter, the process moves one step further. The following shows what it looks like after `exit` has been typed a few times:

![](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/z3FhjrSJsGwcj2wXOyp9/image.png)

After a while, the screen turns to the custom boot images:

![](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/TsbhcQYYV7NOy1Lrn8CG/image.png)

You can also review all available built-in console variables by running `help`, or use the `config` command to get a graphical view of all values. The help output shows available commands:

![](https://content.gitbook.com/content/oPMTFuBb6yV8Wq1KUzxo/blobs/31ZsAJx8qmN3aqaPB5Wb/image.png)

You can then dig around, view variables and troubleshoot to your heart’s content. Typically, you will have been directed here by 2Pint Software support staff.

### Step-by-step network diagnostics

If an issue arises, follow the steps below to gather information that you can provide to 2Pint Software support.

1. Note the make, model and, if possible, the firmware version.
2. Note the iPXE binary being used, such as **snponly\_x64.efi**.
3. Note the version of 2PXE Server being used.
4. As the machine boots the iPXE binary, press the **'C'** key on the keyboard multiple times to get to the iPXE console.
5. Run **'ifstat'** and record the output (a mobile phone photo is fine).
6. Run **'ifconf'** and record the output.
7. Run the **'route'** command to show the default gateway IP address used.
8. Run `ping <IP>`, replacing `<IP>` with the default gateway address shown in step 7.
9. Record the output.
10. If the ping succeeds, press **Ctrl + C** to stop the ping command.
11. Disable BranchCache with the **'set peerdist 0'** command.
12. Try loading a small file from an HTTP path using the command **'initrd <http://server/somesmallfile.bin>'** and see if it works. IISStart.png is a good file to download, because it is typically available on any IIS server at **<http://server/iisstart.png>**.
13. If it does not work or hangs, record any error codes, and run **'ifstat'** and record the output.
14. Try loading a larger file from an HTTP path using the command **'initrd <http://server/somelargerfile.bin>'** and see if it works. Ensure you can download the file from a Windows machine as well before trying iPXE.
15. If it does not work, record the error code, and run **'ifstat'** and record the output.
16. If all of the above fails, run the following commands in sequence and try again:

    **'ifclose'**

    **'ifopen'**

    **'dhcp'** Then retry from step 12 if possible.
17. If all of the above works, move on and try HTTPS, using an HTTPS URL.
18. If all of the above works, re-enable BranchCache with the **'set peerdist 1'** command and retry from step 12.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://documentation.2pintsoftware.com/ipxe-ws/4.0/troubleshooting/ipxe-boot-diagnostics.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
