Diagnostic Data for Support

pfSense® software includes a function to gather diagnostic data for support purposes. The data collected by this function can be useful when diagnosing issues, especially when working with Netgate TAC or community members on the Netgate Forum. This information may also be referred to as “Status Output”.

This function is handled by an unlinked script at /usr/local/www/status.php. The script produces output and an optional archive containing a wide array of information from an installation.

Warning

Though the script makes an effort to remove private information such as passwords, keys, and other secrets, the output may still contain sensitive data. This is especially true when it comes to packages which may use non-standard names for items in the configuration.

Always inspect the output data to ensure it does not contain any private information.

There are multiple ways to invoke the script, both in the GUI and through the shell.

View and Download Diagnostic Data in the GUI

This script is not linked from any menu as it’s not a function users would need to access on a regular basis.

To load the script, first connect to the GUI and then add /status.php to the end of the URL.

For example: https://x.x.x.x/status.php

Note

The page can take a while to load depending on the hardware.

The script will create an archive with the diagnostic data along with a fa-download Download button to easily download the archive file.

By default the script also outputs all of the diagnostic data to the browser which can make it easy for users to inspect. This output can be suppressed, see Script Options for details.

Generate Diagnostic Data Archive in the Shell

The script can also be invoked from the shell if the GUI is unavailable. Additionally, in some cases the script may fail to run in the GUI but succeed from the shell. The script can be run from the console (video or serial) or via SSH.

To start, connect to the firewall console or enable SSH and connect using an SSH client.

Note

This script requires admin or root privileges, so use either of those usernames or use the Sudo Package to run the script from another user.

When connected to the console or SSH use option 8 from the menu to load a shell prompt and then execute the script:

php -f /usr/local/www/status.php

The script will gather the data and create an archive file at /tmp/status_output.tgz. This file can then be copied off the firewall using one of the methods covered later in this document.

Script Options

When invoking the script there a couple options that control its behavior:

archiveonly:

When set, suppresses the output of the script in the GUI so that it only generates an archive for download purposes.

This option is only valid in the GUI as the console method only supports archive output.

nocleanup:

When set, the script leaves behind all of the individual diagnostic data files in /tmp/status_output/ which is handy for inspecting the data directly in the shell without using the archive file.

To use the options in the GUI, they must be passed as query parameters, for example:

  • https://x.x.x.x/status.php?archiveonly

  • https://x.x.x.x/status.php?nocleanup

  • https://x.x.x.x/status.php?archiveonly&nocleanup

When running the script in the shell, pass the option the script filename:

php -f /usr/local/www/status.php nocleanup

Copying the Diagnostic Data Archive

After using the script users can copy the archive file (/tmp/status_output.tgz) off the firewall in a variety of ways.

Download from the GUI

The easiest way to download the archive from the GUI is to use /status.php directly in the GUI. If that is not viable, use the Download function on Diagnostics > Command Prompt to download the /tmp/status_output.tgz archive file after generating it in the shell.

Download Using SCP

If the SSH daemon is enabled on the firewall, then an SCP client can copy files from the firewall remotely. Alternately, SCP can copy files from the firewall to a remote SSH server from the shell.

See Accessing the Firewall Filesystem with SCP for information on setting up and using SCP.

Copy to a USB Drive

Alternately, bypass the network and copy the archive file to a USB drive by following the procedure in Copy Files to a USB Drive.