New FreePBX users guide to diagnosing problems

[editor's note: reading documentation (yay for you!) and forums is recommended first before hitting the IRC. The only time you should need IRC is if you are trying to make FreePBX do something not-yet-supported.- jms]

I'm creating this document in order to bring new users up to speed
on some basics of troubleshooting. Read this BEFORE you go onto the
#freepbx IRC channel or post in the FreePBX forum. Some of this should probably be in a FAQ document of some kind but as far as I know, we don't have one of those yet.

Before we begin, please understand that there is a distinction between Asterisk, FreePBX, and Trixbox. Briefly,

• Trixbox is a complete distribution that includes the
  CentOS operating system (a Linux distro), the Asterisk PBX software,
  FreePBX, and a few other programs and scripts. At the moment, it's the
  easiest way for new and inexperienced users to get Asterisk and FreePBX
  up and running, though that may change in the near future.

• Asterisk is the underlying PBX software. It is normally configured using text-based configuration files.

• FreePBX is a web-based GUI interface and configuration
  file generator for Asterisk. Basically it allows to users to set up
  their configuration using point-and-click, and filling in some
  information in text boxes (usually with "flyover" help boxes that
  assist the user). FreePBX makes it far easier to make Asterisk work the
  way you want it to, and gives you access to features not available in
  Asterisk (unless you were to write the configuration scripts yourself).

A primary source of help for new users is this wiki
and the #freepbx channel on IRC (use the server irc.freenode.net). But
the thing to remember is that the #freepbx channel is primarily for
help with problems related to FreePBX. If it's a problem that ONLY
affects Trixbox users, or it affects ALL Asterisk users (including
those not running FreePBX), there's less of a chance you'll be able to
get help there, though you are welcome to try.

If you're not familiar with IRC (Internet Relay Chat), not to
worry, there in an IRC client preconfigured and built into FreePBX. Go
to the Tools menu, then Online Support - read the text on that page,
and then (if you agree to the terms of use on that page) click "Start
IRC" and you should be taken into the #freepbx channel automatically.
If you don't agree with the terms of use on that page, you can use a
different IRC client (Wikipedia has a List of IRC clients).

We'll talk more about IRC usage a bit further down the page.

As a new user, you need to know is how to access your FreePBX
system from another box on your network. Ideally you should be able to
run your FreePBX system without even having a keyboard or monitor
connected (that's the ideal, but the fact remains that if
everything comes crashing down you will need to directly access the
system. But 99% of the time you should be able to work from another
box).

I'm going to skew these instructions just a bit toward people who
have more experience with Windows than Linux, simply because that's the
situation I'm in, and because I think the Linux folks will have no
problem picking up on the differences.

The first thing that a Windows user should do is install PuTTY on
their desktop system (NOT on the Asterisk box). PuTTY is a free
implementation of Telnet and SSH for Win32 and Unix platforms, along
with an xterm terminal emulator. It is useful for securely accessing
the Asterisk CLI and the Linux command line. Use these links for more information and to download the program.

Use PuTTY (or ssh if you're a Linux user) to access your Asterisk
box. After logging in, you will initially be at the Linux command
prompt. As this point you need to note the difference between the Linux
command prompt and the Asterisk Command Line Interface (CLI). These are
NOT interchangeable; if someone tells you to type something at the CLI
and you do it at the Linux command prompt it won't work!

You enter the Asterisk CLI by typing:

asterisk -vvvvvvvvvvr

Followed by the ENTER key. The number of v's control the
"verbosity" of output and more is generally better when you're trying
to fix a problem. Should you need to return to the Linux command
prompt, just type exit then ENTER.

Now, let's say that you're having a problem receiving incoming
calls. While you are sitting at the CLI prompt (NOT the Linux prompt),
place a call to your system. You should see a bunch of output scroll
by. If you are lucky, you may see a line that indicates an obvious
problem. If you don't, copy and paste the entire output into a
pastebin, remove any identifying information you don't want to reveal
(such as personal phone numbers - replace with a dummy number such as
all zeros or xxxxx or something). Normally the CLI won't print any
passwords, but for future reference, never put a password in a
pastebin!

What's a pastebin, you ask? It's a place on the web to paste your
issues. You paste in your CLI output or configuration files or
whatever, and it will return a page with a URL. You can then point
people in the #freepbx IRC channel to that URL if you need help in
resolving your problem. They can see what you've seen and comment on
it. The best pastebin site to use (because it is faster and more
responsive than some others) is http://pastebin.ca

I will say again, don't put any information you don't want others to see in a pastebin!!! That particularly includes passwords and perhaps phone numbers,
if you wish to keep them private. Some people may also wish to remove
information such as Internet addresses - that is up to you.

Now, let's say you have a really thorny problem that's not revealed
in the CLI output. Someone may ask you to look at the Asterisk log.
Generally, that means you'll want to view this file:

/var/log/asterisk/full

This can be a VERY large file on some systems. So before you begin
your diagnostics, FIRST go to the Asterisk CLI and enter the command:

logger rotate

Followed by the ENTER key. (By the way, did I mention you can get a
list of all valid commands at the Asterisk CLI prompt by typing help and ENTER?)

Now you want to get some debugging information into the log. So,
assuming that you are dealing with a problem that affects a sip trunk
or sip device, enter these two lines at the CLI:

debug level 4

sip debug

Now when you try to place a test call, you should see much
additional output, both on your screen and in the log. By the way, if
the issue is with an IAX channel instead of a SIP channel, use iax2 debug instead of sip debug. And when you are ready to turn off debugging, put the word no in front of debug, e.g. sip no debug.

When you place your test call, note the exact time (including
seconds) that it should be going through - this will help you find it
in the log.

To view the log file, you can use any file viewer. Some people may wish to use nano from the Linux Command Prompt:

nano /var/log/asterisk/full

Others may wish to use the Linux "tail" command, or the file viewer
in Midnight Commander. You can bring up Midnight Commander from the Linux Command Prompt:

mc -a

Then navigate to the log file and press F3 to view it.

Often, what you will be looking for is the sip invite packet and
Asterisk's response. You may see a line that tells you exactly what the
problem is. But if you do not, again you can paste this into a
pastebin, observing the earlier caveats about not revealing passwords
or personal information. Someone more experienced may be able to show
you what the problem is.

If you learn the above basics, others will be much more willing and
able to help you. People on the #freepbx channel get a little tired of
explaining these same basics over and over, and sometimes new users are
ignored for that reason. It's not that we don't want to help you, it's
just that after you've had to walk someone through the above procedures
for the 999th time, you really don't want to do it again.

A few other tips:

When using the #freepbx IRC channel:

• Don't post messages saying "Hello?" or "Can anyone help
  me?" and then wait for a response. Just post your problem and what
  steps you've taken to diagnose it in your first messages. As the saying
  goes, "Don't ask to ask, just ask. Those who ask to ask risk being
  axed!"

• If no one responds immediately, don't keep reposting the same message every couple of minutes. It just annoys people.

• Remember that most of us can only help one person at a
  time, or maybe two at most. If traffic is really heavy, go ahead and
  ask your question, but realize that no one may be able to get to you
  for a few minutes.

• If you post and no one responds, it most likely means that
  no one is on the channel AT THAT MOMENT that can help you. A BIG
  mistake that newbies make is to come on the channel, ask a question,
  wait a couple of minutes, and then make some snide remark and leave.
  Not only does that make people NOT want to help you, but had that
  person stuck around for a bit their question might have been answered.
  I have seen people leave the channel as I was in the process of typing
  an answer to their question! There are times of day when a lot of
  "experts" are online, and other times when there will be no one on the
  channel but newbies like yourself. Also, keep in mind that even when
  someone is online they may get interrupted by a phone call, or employer
  or family demands, or whatever. Patience is a virtue (and will often be
  rewarded eventually) on IRC.

• Try to use complete English sentences, and think about
  whether your question actually makes sense before you press the ENTER
  key. #freepbx users are more likely to ignore questions they can't
  understand. We realize that English is a second language for some, and
  we'll try to work with you up to a point, but if we can't understand
  you at all, then you probably won't get helped.

• When someone who is trying to help you asks you a question, answer that question!
  Nothing is more infuriating to the experienced folks than to ask a
  question in an attempt to try and diagnose a problem, and then have the
  person who is having the problem either not respond, or respond with
  something totally unrelated to the question. Usually when an
  experienced person asks you a question they're trying to determine
  which of several possible issues you may have, or eliminate possible
  problems from consideration. Remember they cannot read your mind, nor
  see what is on your screen, so answer the question and you are far more likely to get to the bottom of your problem.

• Consider leaving the channel open for some time (several
  hours at least) after you post, whether or not you get an answer. First
  of all, people come onto the channel from all parts of the world and
  it's not that uncommon to see a question get answered HOURS after the
  person originally posted it. It's also not that uncommon to see someone
  get questionable advice in the first few minutes (remember, there are
  other newbies like yourself on the channel) and much better advice a
  bit later on. So, don't be so quick to leave the channel. Besides,
  maybe YOU can help someone else!

If you can't get an answer on IRC (or have a complicated question), consider using the FreePBX Forum.
This is a new one that should be easier for people to access and use,
since a lot of folks seemed to have a problem accessing the old one.

Don't ignore the FreePBX wiki pages, they are a wealth of information for new and existing users alike. For example, there is a page on Resolving Audio Problems that will be very useful to those setting up FreePBX and Asterisk for the first time.

NEVER, EVER manually edit a configuration file that does not have
the word "custom" in the file name. There are a few minor exceptions -
you can modify sip.conf and iax.conf to allow additional codecs, you
can modify sip_nat.conf to resolve one-way audio problems,
etc. but the thing to keep in mind is that any file with the word
"additional" in it will be rewritten by the system every time you click
the red bar in FreePBX, and most other configuration files (except for
the ones with "custom" in their name) will be overwritten every time
FreePBX itself is upgraded. Many VoIP providers will tell you to
directly modify extensions.conf - DON'T DO IT,
because any changes you make there will not be preserved! You should
create a new trunk and put the settings they give you into the trunk
settings. Remember, you are using FreePBX so that you don't have to
deal with Asterisk configuration files directly. If you want
to write your own Asterisk configuration files, then you shouldn't be
using FreePBX. You can't have it both ways, you either use FreePBX or
you don't. But for those really special circumstances where you
absolutely need to do it manually, you can modify the "custom" files
and FreePBX will not change them.