The Basics of Troubleshooting

Troubleshooting Linux can be very confusing due to all of the moving parts. This doc will aim to cover as much as possible while still being understandable. If you believe something is missing or could be improved, please submit an issue to help to try and get this to be as complete as possible.

Log files

  • /var/log/ - Contains most log files might be needed to troubleshoot an issue
  • /var/log/syslog - Contains messages from the kernel and other programs and services
  • /var/log/apt/history.log, /var/log/apt/term.log, and /var/log/dpkg.log - All are files that will help to show where an error occurred during an package update
  • /var/log/auth.log - Contains system authorization events
  • /var/log/dmesg - Contains kernel ring buffer information
  • /var/log/message - Contains system messages
  • /var/log/Xorg.0.log - Contains log messages from X
  • /var/log/lightdm/lightdm.log - Contains events from lightdm
  • /var/log/kern.log - Contains kernel messages only
  • ~/.xsession-errors - Contains errors that occur within the Linux graphical environment from the X window session

Different programs may have log files in their own locations as well. Checking the man pages (man package) will likely provide the information needed to either find the file or find a different location that will contain the information you need.

Commands and processes

Anything mentioned should have their man page looked at for more details. Additionally, if there is an issue with a graphical tool that does not display an error try running it through the command line.

  • journalctl - Will show the contents of the systemd journal
  • dmesg - Will show kernel events, allows to see errors
  • ip - Network configuration
  • service - runs a System V init script or upstart job
  • systemctl - Used to control the systemd system and service manager
  • df - See how much disk space is free, which may prevent certain things
  • top - See lots of information about the computer, can help to pinpoint CPU, memory, etc issues
  • dpkg - Allows for troubleshooting of packages (along with normal functionality)
  • apt - Also allows for troubleshooting of packages (along with normal functionality)
  • ps and kill - Combo to find a process that may be causing problems and kill it
  • tail (-f specifically) - lets you watch log files be written to in real time

The most important tool

Google.

Google will be the most important utility for almost all cases of troubleshooting. Utilizing log files and error outputs, somewhere on Google there will likely be a reason and a solution.