Update troubleshooting.md

troubleshooting.md

@@ -5,17 +5,15 @@ Issues covered so far:
 
 * [COMSAT is crashing on start](#comsat-is-crashing-on-start)
 
-through out the document you will see certain special characters mentioned. They are slightly different depending on your keyboard and terminal
+Throughout the document you will see certain special characters mentioned. They are slightly different depending on your keyboard and terminal
-* `$` means the ALT or ESC key
+* `$` means the ESC key
 * `^` means the CTRL or STRG key
-* `<escape>` means the ALT or ESC key in EMACS
+* `<escape>` means the ESC key
-* `<control>` means the Control key in EMACS
+* `<control>` means the CTRL or STRG key
 
 ## COMSAT is crashing on start
 Thanks to eswenson for the intial steps here
 
-In order for INQUIR entries to stick, you must have COMSAT running. 
-
 If you run PEEK, you should see two COMSAT jobs. One has the JNAME IV and the other JOB.nn.  If these jobs are not present, then COMSAT may have started and died or not started at all
 ```
 *:peek
@@ -39,6 +37,10 @@ Logout time =         Lost 0%  Idle 98%  Null time = 5:07
 As you can see above none of the COMSAT processes are running.
 
 There are several reasons why COMSAT may die upon startup The most common are:
+* Network configuration issues
+* Uninitialzed Mail directory structure
+* Other configuration issues
+* 
 Lets start going through those one by one:
 
 ### Network parameters for COMSAT are not correct.
@@ -48,6 +50,10 @@ When you bring up KA ITS, you'll see a message on the operator console like this
 TOP LEVEL INTERRUPT 200 DETACHED JOB # 4, USR:COMSAT IV     12:09:12
 
 This means that COMSAT has crashed.
+The next series of steps assumes you have logged into ITS using
+```
+< your username>$$u
+```
 
 If you look at the IP address that COMSAT is configured with:
 ```
@@ -56,7 +62,12 @@ $l .mail.;comsat launch
 bughst/'NEW$:   SHOWQ+50,,PAT+6   =30052000544
 ```
 
-you'll note that that octal address is: 192.168.1.100
+you'll note that that octal address translates to: 192.168.1.100
+
+>![NOTE]
+> To convert from the Octal representation of the IP Address to the tuple representation you can use the approach listed below at
+>(Convert IP address)[#convert-ip-address]
+
 
 If you look at the value that ITS has for the machine's IP address:
 
@@ -82,6 +93,7 @@ The easiest fix is to:
 4) fix COMSAT's mailing lists file
 5) restart COMSAT
 
+### Fixing the host table
 To fix the host table, change the line:
 ```
 HOST : CHAOS 177002, 192.168.1.100 : DB-ITS.EXAMPLE.COM, DB : PDP-10 : ITS : :
@@ -100,6 +112,7 @@ the `FN2` of the `SYSHST;H3TEXT NNNNNN` you just created.
 
 Now your host table matches your ITS IP address.
 
+### Fixing the COMSAT binary
 Next, you need to fix COMSAT.
 
 To do that, create a job for COMSAT:
@@ -130,6 +143,7 @@ Now, you have an correct `.MAIL.;COMSAT LAUNCH` executable.  This will be
 launched by `TARAKA` on startup, or by `:MAIL` when invoked if `COMSAT` isn't
 running.
 
+### Create the COMSAT database files
 However, before you do this, you need to make sure that COMSAT's database
 files are created.
 
@@ -188,6 +202,7 @@ kill the job by typing:
 
 Then, exit PEEK with the "q" command.
 
+### Verify the changes
 Now, send yourself a message:
 ```
 :MAIL <your-uname>
@@ -207,5 +222,57 @@ You also should see that your mail was delivered. Type:
 ```
 to read (and optionally delete) it.
 
+### Convert IP address
+If you are wondering how to convert octal IP addresses on ITS to the familiar octet pattern, see this example:
 
+Let’s say you want to convert 1200600006 to a standard-formatted IP address.  First ensure that the value has 12 octal digits.  In this case, you’ll have to add two 0s at the left to get:
+
+001200600006
+
+Then, break that value up into octal values:
+
+001 200 600 006
+
+Then, convert the above to binary:
+
+000 000 001 010 000 000 110 000 000 000 000 110
+
+Then, group into 4 (ignored) bits, followed by 4 8-bit bytes:
+
+0000  00001010 00000011 00000000 00000110
+
+Then, ignoring the first 4 bits, convert each 8-bit byte to decimal:
+
+      10      3        0        6
+
+So 10.3.0.6 is the same as 1200600006 octal.
+
+Lars created a shell script that will do the trick too.  You *have* to make sure the input is 12 octal digits long when invoking it:
+
+```
+#!/bin/bash
+
+if [ $# -eq 0 ]; then
+ echo "Please provide an IP address as an argument"
+ exit 1
+fi
+
+octal=$1
+ip=""
+for i in {1..4}; do
+ octet=$(echo $(( $octal >> 8*(4-$i) & 255 )))
+ ip="$ip$octet."
+done
+
+echo ${ip%?}
+```
+You could invoke it like this:
+
+`./ipconvert.sh 001200600006`
+
+And it should respond:
+
+`10.3.0.6`
+
+But it’s much more fun to do it the hard/manual way!