Ok, so I have been in Tech Support for most of my career and troubleshooting has become a skill I use without thinking about it.

Recently, I have been reading some posts on the FreeBSD forums about Xorg problems. I thought I would write a post about “How to troubleshoot Xorg.

Step 1 – Document the problem clearly

1. Reproduce the issue and store any output errors or screenshot them (if possible) as needed.
2. Reproduce the issue again but this time while doing so, document each step you took to reproduce the issue.

Note: You wouldn’t believe how many issues are solved during the process of documenting the steps to reproduce an issue.

Step 2 – Gather Hardware Details
Lets make sure we know what is in your system. Gather the output of this command to get the AGP, PCI, or PCI-Express devices in your system.

# pciconfig -lv

Step 3 – Gather Installed Software Details
We are going to run some commands here. The output of every command you run should be stored into a text file. If you are getting help from a forum, a mailing list or you are paying for support for a company, they are going to want as much information as possible.

Note: I assume you have sshd enabled and that you can both ssh to your machine and sftp to your machine. A windows ssh tools is PuTTY. A windows sftp tool is WinSCP.

1. Get the basics about the installed FreeBSD system.# uname -a
2. Make sure Xorg is installed and that any other required software or add-on software such as the Windows Manager (KDE, GNOME, Fluxbox) is installed.# pkg_info
3. It is often good to just get the list of Xorg packages:# pkg_info |grep xorg
4. Look in the package list to make sure that if you are using an NVidia or Intel driver that requires the installation of a binary package (as they are not open source) that you have installed the driver.

Step 4 – Gather Software Configuration Details

1. Gather the Xorg configuration file. Now one does not always exists, but if it exists, it usually located at /etc/X11/xorg.conf
2. Gather the /etc/rc.conf file so you can see what it is configured to enable.
3. Gather the /boot/loader/loader.conf file so you can see what it is configured to enable.
4. Gather the ~/.xinitrc or /home/username/.xinitrc file.

Step 5 – Gather logs and examine logs for errors

Gathering Logs

One process for making it easier to view logs and find the cause of errors. It is an obvious procedure to some.

1. Backup all logs.
2. Delete logs once backed up.
3. Duplicate the issue.
4. Gather the logs (both backed up and new logs).

The key is to limit the amount of data to go through. So by deleting the logs and duplicating the issue as fast as possible, your logs will be as small as possible and easier to go through.

1. Gather the /var/log/Xorg.0.log file.
2. You might want the /var/log/messages file.

Examine the logs for errors

Now that you have the smallest amount of data possible, it may be easier to search the logs for errors.

1. Start out by greping or searching for words like fail, error, etc…
2. If you didn’t find anything, then visually scan down the logs.

A nice way to watch a log file live as you duplicate the error is to use tail.

1. Open two shells, maybe one directly on the system and one through ssh.
2. In one shell, run this command to watch a specific log file, such as Xorg.0.log. (For this use the ssh shell if you have sshd enabled and opened on through ssh)# tail -f -n 50 /var/log/xorg.0.log
3. Duplicate the issue in the other shell. (This would be the shell directory on the system.)
4. Watch the dynamic log live and try to find the line where the error occurs.

Tip #1 – Enable sshd when testing

Sometimes running Xorg may result in a black screen and you can’t switch between ttys either using Alt+F# so you may be tempted to hard power off. Most the time if you have enabled sshd, you can ssh in and kill Xorg or reboot gracefully, saving you a hard power off.

Tip #2 – Try running Xorg with and without an xorg.conf

Supposedly you don’t need and xorg.conf always but there are times when you would want one. I have seen forum posts where the solution goes both ways. One user’s issue was resolved by not using an xorg.conf and letting Xorg just start and automatically handle everything. Another users issue was resolved by using an xorg.conf. So try it both ways.

Tip #3 – Use the FreeBSD forums correctly

If you have all of the above data and you still have an issue, if you go to Xorg section of the FreeBSD Forums, and make a post, you will be able to provide an educated, detailed question.

There is fine line between posting too much data or too little data and posting the perfect amount so a reader can have enough data to resolve your issue. I would say it is rare should post all configs and logs, but it also should be rare that you post a question alone without any details.

Ok, so this may not be complete. If you have anything to add please comment.