Finally a troubleshooting wiki page to point to

[RobJ]

Well, I finally edited my first wiki page!  I started with the 'Troubleshooting' page on the unRAID wiki, created an intro to troubleshooting an unRAID problem, then a section on capturing the syslog, then a section on creating an appropriate post about a users problem.  It's my first ever, so be kind!  I would really like to hear constructive criticism as to what could improve, both as to content and as to style.  I did not touch the bottom 2 sections, they were already there, but they look like they need a little love too.

 

I hope others will feel like adding to the wiki, or editing and improving what is there already.  I found it a little weird, but not hard.  Italics require a pair of apostrophes before and after the word or phrase to be italicized, eg. ''italicized words''.  Bold requires 3 apostrophes before and after, eg. '''bold words'''.  Internal links to other pages on the wiki are simply the page name inside a double pair of square brackets, eg. [[Wiki_Page]].  External links are simply the URL, a space, and the text to display, surrounded by a single set of square brackets, eg. [http://lime-technology.com/wiki/index.php?title=Troubleshooting Troubleshooting problems with your unRAID server].  The main heading is surrounded by a pair of equal signs on both ends, eg. ==Main heading==.  Subheadings use 3 equal signs before and after, eg. ===Subheading===.  The rest is ordinary text.  Now you too have no excuse, as that is about all you need, to get started!

 

I added a link to this Troubleshooting wiki page in my signature, and I recommend it as a link to give others, to help them get started with solving their problems.  In it, I of course emphasized the need to capture and attach a syslog, without waiting to be asked!  I have no doubt that others will have good suggestions about things to add to this page.  Feel free to mention them here, or add them yourself to the wiki.  It is not my page, but all of ours.

 

[WeeboTech]

I added some commands after the cp of syslog so the files are not hidden.

Also added a note about syslinux -ma

 

I have s special shell called save_syslog. Perhaps we should have tom add it to the distro to make it easier on the newbies.

Thoughts?

 

#!/bin/sh
# Reads syslog converts to dos, saves syslog to OUTPUT_DIR as OUTPUT   

if [ "${DEBUG:=0}" -gt 0 ]
   then set -x -v
fi

P=${0##*/}              # basename of program
R=${0%%$P}              # dirname of program
P=${P%.*}               # strip off after last . character
O=${P%_*}               # Operand
D=${P#${O}_}            # Data (last param before _ character)

SAVE_ROTATE="yes"       # Move under other line to save syslogs on rotation
SAVE_ROTATE="no"

INPUT=/var/log/syslog
OUTPUT="syslog-`date -r ${INPUT} +'%Y%m%d-%k%M'`.txt"
OUTPUT_DIR=/boot/var/log

# Normally we can use $0 if called with a full pathname.
# in my environment it is called with <fromdos $0 | sh
# so I have to use the full program/pathname for this program
# change to suite your taste  
THISPROG=$0
THISPROG=/boot/config/rc.local/S99-syslog-save


# Insure output directory exists
if [ ! -d ${OUTPUT_DIR} ]
   then mkdir -p ${OUTPUT_DIR}
fi

# No size to input, skip
if [ ! -s ${INPUT} ]
   then exit
fi

# Remove logs from OUTPUT_DIR > 7 days
find ${OUTPUT_DIR} -mtime +7 -name "syslog*.txt" -exec rm {} \;

# convert input to dos for dos machines via samba
todos < ${INPUT} >> ${OUTPUT_DIR}/${OUTPUT}

# save modification time to be same as original
touch -r ${INPUT}   ${OUTPUT_DIR}/${OUTPUT}

# set perms for unhidden and readable
chmod 666 ${OUTPUT_DIR}/${OUTPUT}

# if save files via daily rotation, set variable above to yes
# This puts a call to this script in the pre-rotate section for /var/log/syslog
#

if [ "${SAVE_ROTATE}" != "yes" ]
   then exit
fi

# upon first invocation if call to this script not present
# and saving of syslogs on rotation if selected

if ! grep ${THISPROG} /etc/logrotate.conf > /dev/null 2>&1 
   then while read LINE
        do
            echo "${LINE}"
            if [ "${LINE}" = "/var/log/syslog {" ]
               then echo "prerotate"
                    echo "   ${THISPROG}"
                    echo "endscript"
            fi
        done < /etc/logrotate.conf > /etc/logrotate.conf.tmp
        cat < /etc/logrotate.conf.tmp > /etc/logrotate.conf
        rm -f /etc/logrotate.conf.tmp
fi

[SSD]

Well, I finally edited my first wiki page!  I started with the 'Troubleshooting' page on the unRAID wiki, created an intro to troubleshooting an unRAID problem, then a section on capturing the syslog, then a section on creating an appropriate post about a users problem.  It's my first ever, so be kind!  I would really like to hear constructive criticism as to what could improve, both as to content and as to style.  I did not touch the bottom 2 sections, they were already there, but they look like they need a little love too.

...

Excellent!  I just read the wiki page and think you did a great job.  Feel free to add something at the top similar to what I am suggesting below.  It might help the ADHD newbies.

 

One suggestion (from someone that has tried to use the WIKI to solve problems and gave up) - be specific about the version(s) of unRAID that this procedure works with.  I found some wiki posts for old versions that were no longer valid.  This was an immediate red flag that I couldn't trust the wiki.  If you are a newbie in trouble, the worst thing is to read something, and try to do it, only to find that it doesn't work that way anymore.  After having that experience, I stopped looking at the wiki.  If we are going to rebuild wiki confidence, posting version numbers will help.  It does 2 things - one it gives confidence that the procedure has been tested with the version they are running, and two it lets people know that the wiki IS being maintained.

 

But the problem is that most people having a problem are in the "my house is on fire" mindset, and typically do NOT search for help sources, they immediately cry "help!".  Even if there is no fire, a person starting to search for help can quickly get frustrated.  For example, I've noticed that the "Search" box is not very helpful - you really need to go to advanced search to find stuff (not sure why). 

 

But some of this is human nature, and I think we've all been guilty at one time or another.  Many forums have "sticky" messages that give newbies instant answers to recurring questions.  These seem more effective at getting a quick read before an emergency post.  If there were one called "How to get help", that gave a 10 step cookbook style set of things to do, with pointers to the wiki for more info, I think it would cut down on the traffic. Something foolproof and specific, for example:

 

***********************************************

 

If after searching the forums (use advanced search) and wiki (http://lime-technology.com/wiki/index.php?title=Main_Page) you are not able to resolve your problem, here is an (almost) foolproof way of asking for help that will give the experts the info they need to help you quickly.  If you don't provide enough detail, you risk annoying the gurus who may not answer your cry for help.  This procedure will work on ALL versions of unRAID from 4.2.1 through 4.3 beta 6.

 

Sometimes the worst thing you can do is try something that could make the problem worse, so avoid the urge to try anything risky!

 

1.  Go to the unRAID server

2.  Logon (unless you changed it, userid is "root" with no password)

3.  Enter this command cp /var/log/syslog /boot/syslog.txt

4.  Then enter this command chmod a-x /boot/syslog.txt

5.  Shutdown the unRAID box by entering these commands

stop

sync

powerdown

6.  Wait for computer to power off

7.  Remove the USB stick from your unRAID server and put into your desktop computer

8.  Start a new thread on this forum

9.  Enter a description of the problem, title it something useful like "HELP:  Drive with all my data says its unformatted"

10.  Attach the syslog.txt file from your flash drive to the post

 

Take a valium and wait patiently for a response. 

 

***********************************************

 

If this were a sticky, and updated with each new version to indicate it still applies, I think we'd get fewer problem reports with no syslogs.

 

[WeeboTech]

Excellent point about the Wiki and the first basic steps to getting help

I think a sticky for that is sorely needed.

[RobJ]

Also added a note about syslinux -ma

 

Good to see it!  Should cut down on many of the USB prep problems.  I added an intro and link to Tom's initial flash drive setup and note about volume label.

 

I also added a stub section for general hardware issues.  I would like to see a nice step by step approach to isolating a hardware problem.  Joe has some great posts listing a number of things to check, would be a good start for this section.

 

I added a More Links section at the bottom, with only 2 links now.  One is a link to Tom's Troubleshooting page on his site, with help on using Telnet.  The other is a link to Tom's unRAID Manual.  There's room for lots more links...

 

Might be nice to see a 'Common problems and how they were fixed' section, with just links to relevant forum threads, with a bit of description of the problem fixed.  This would be an easy section for many users to contribute to, just a link and a description.

 

I added some commands after the cp of syslog so the files are not hidden.

 

And a good command it is.  I may edit this section somewhat though, to start with the simplest form, then deal with the more complex stuff.  (bear with me, here comes more discussion than the point is worth...)

 

Our audience could be characterized as 4 somewhat distinct groups of users, those with no experience, with some experience, with a lot of experience, with a lot of Linux but no unRAID experience.  I like to aim at the no experience group, but without boring the rest.  I've been very impressed with some who have created a great balance in their writing, doing it in a way that is clearly aimed from the top to help the newest user, yet laid out in a way that works well as a reference manual for those with more experience.  Users can read everything, or they can easily skip over the intros and reassuring hand holding and jump to the meat of that section, to the answers they need.  I in no way have the writing talent or training to do that, but it still seems a worthy goal to aim for.

 

I like the idea of starting by emphasizing the absolute shortest form of copying the syslog, in as simple a way as possible.  This form (cp /var/log/syslog /boot) doesn't even have a destination filename, therefore requires no customization at all, or explanation of same.  You don't have to go anywhere with cd, apart from getting to a Linux prompt.  You don't have to stop, start, sync, mount, umount, or anything else.

 

Then I'll move through the more complex issues of making it usable, such as using your command, and what to name the file.  I like to see it with a timestamp, but that seems unnecessary here, so I think I'll switch back to suggesting just syslog.txt for attachment purposes.

 

 

I have some thoughts on your script, but I'll split it to a separate post.  I like the idea, and agree it would be great if Tom would add something like it to the unRAID startup.  There a several changes I would like to suggest though, and I wanted to comment on Brian's excellent work too, but tired now...

 

[SSD]

RobJ - I added my little piece to the top.  If you feel it is too duplicative, feel free to remove.

[Joe L.]

I agree, we need to constantly be aware of the different levels of experience of various users.

 

To be "critical" is to step back and read all the requests for help... only then can you understand that the instructions you might think are most clear are still difficult for some users.  Let me take the instructions given a few posts ago as an example...  (and they are excellent instructions for all but the complete Linux newbee)

 

They start with this:

1.  Go to the unRAID server

2.  Logon (unless you changed it, userid is "root" with no password)

 

I know what is intended, but as a beginner, how do I "Go to the unRAID server"  It is computer on the desk?  What do you need to do to "Logon?"  What is a "userid?"    If there is no password, why is it asking me for one? 

 

It is so easy to get confused... recently one user posted a picture of their console, where diagnostic messages had written across the screen making them weary of typing anything. You can see their post for help here:  http://lime-technology.com/forum/index.php?topic=1757.msg12494#msg12494

 

A simple "How to log into the system console" is as important to some as how to copy the system log once you get there.  The experienced will not read much of the "how to log in wiki" other than to learn the login name to use.  The beginner will read every word and still come here for advice.

 

I agree, good clear instructions are needed.  To help us support him, in addition, a simple comand to copy the syslog should be added by Tom to the root of the drive.

 

Here is as good as any for Tom to add.  Name it "s" and make it standard in the distribution. it creates a file named for the current date and adds in a few items we often ask users about.

 

(grep -v "registered to:" /var/log/syslog; ls -l /dev/disk/by-label;mount;/root/mdcmd status;) >/boot/syslog_`date +%m%d%Y`.txt

 

A person would only have to log in and type "s" to capture their syslog.

Joe L.

 

If something like this was put in the default distribution, it would help everyboody.

 

 

 

Joe L.

 

[WeeboTech]

I also agree that a good diagnostic capture command should be included in the distribution.

 

I would add to that a call to ifconfig

and possibly ethtool to show information about the ethernet port.

I.E. Address assigned (if) and what type of connection to the network. 10/100/1000.

 

[SSD]

Added a hard disk failure section.