README-DIY.txt
2005-12-18 jtodd@loligo.com  v1.1

Self-Installation Instructions for Soekris/Astlinux 0.2.9

Note: This file assumes you want to build everything "yourself" from scratch.  A pre-built disk image is available if you wish to skip most of these steps.  See README-FIRST.txt for instructions.

---- Start of Instructions ----

1) Download the 0.2.9 image to your hard drive:

zot# cd /tmp
zot# wget "http://mirror.astlinux.org/AstLinux-0.2.9-net4801.img.gz"

You should end up with a file named "AstLinux-0.2.9-net4801.img.gz" in your directory.  It's about 14.4 megabytes in size.


2) Insert the Compact Flash card in your laptop or desktop machine.  Using the "mount" command, determine where the CF card is mounted.  Note the "disk" number (i.e.: /dev/disk3s1 means that the disk number is 3) Ensure that all data has been removed from the card, since we're going to be formatting the card.  The card in the example below is called "NO NAME".

[example shown from an Apple MacOSX laptop]

zot# mount
/dev/disk0s5 on / (local, journaled)
devfs on /dev (local)
fdesc on /dev (union)
<volfs> on /.vol
/dev/disk1s9 on /Volumes/ExternalFirewire1 (asynchronous, local, nodev, nosuid, mounted by jtodd)
/dev/disk2s9 on /Volumes/Weasels (local, nodev, nosuid, mounted by jtodd)
automount -nsl [451] on /Network (automounted)
automount -fstab [454] on /automount/Servers (automounted)
automount -static [454] on /automount/static (automounted)
/dev/disk3s1 on /Volumes/NO NAME (local, nodev, nosuid)
zot# 

If you're running Linux or Windows, I'm afraid I have no immediate help for you but I'm sure that a Google search will start to give you some clues on how to mount/write the image to the appropriately named flash device driver on your system.


3) Unmount the drive, but don't remove the card.  This makes the card available for raw read/writes.  Use the command line version of "umount" in MacOS; don't use the graphical editor.

zot# umount /dev/disk3s1


4) Copy the image onto the CF card:

zot# gzcat -c AstLinux-0.2.8-net4801.img.gz > /dev/disk3

You should see no errors or output as a result of this command, typically.  If the operating system complains about "unknown disk" before you eject, hit the "ignore" or "cancel" button - you don't want to reformat.


5) Remove CF card from your laptop (ignore the unmounting errors) and put into the Soekris 4801.


6) Attach a serial cable to the Soekris, and fire up the terminal emulation program of your choice to communicate over the serial port.  You'll need a null modem.  Settings are 19200/8/N/1.


7) Connect a network connection (RJ45 Ethernet) to the eth0 interface on the Soekris.  This LAN segment should have a DHCP server.  This step is not mandatory, but is convenient.  Further discussion below assumes that you have Internet access for updates and downloads.  You will not need this to be on DHCP forever; just for the "bootstrap" process of configuration.


8) Power up the Soekris.  You should see a boot screen for the Soekris, then the output of Linux booting.  See the "dmesg-0.2.8.txt" file for details of what it should look like.

9) Select "Boot from CF - Use 3rd partition for keydisk" as the GRUB boot kernel option list


10) If you get a failure message with something like this:

  Kernel panic - not syncing: VFS: Unable to mount root fs on unknown-block(0,0)

Then you will need to reboot the device and fix the boot commands.  At the GRUB menu (where it asks which kernel to use) you should hit 'e' to edit the boot commands.   Edit the boot line and change all references of "hda1" to "hdb1".  The "delete" character is control-H.  The system should boot.  Login and modify /boot/grub/grub.conf to make these changes permanently.  (note: filesystem must be mounted RW with "mount -o rw,remount /" first, as this is in a section of the disk image which is normally not mounted read/write.)
This error is caused by cards that have odd geometries or for some reason don't sit well with the Soekris.  If you can, use Sandisk brand cards as they have been found to have no issues with this type of booting problem.


11) The username is "root" and the default password is "astlinux" - log in.


12) First, change the root password with "passwd" (note: system automatically mounts itself read/write and then remounts as read-only after "passwd" is executed, so any further changes to the disk will be impossible without issuing a "mount -o rw,remount /" command after "passwd" has completed.  While not important if you are following these instructions to the letter, it is worth noting to prevent future frustration.)  If you had to specify a different disk partition in step 9, now would be a good time to do that too so you don't have to continually specify hdb if that is what your CF disk requires.


13) [***DON'T RUN THIS INSTRUCTION*** This doesn't work as of 2005-11-21 with 0.2.9 - check to see if astup has been fixed before running this step.  No major problems if you don't run it.  I've left this step included since eventually it will be "fixed".  Until the release of 0.3 of Astlinux, use "astup testing" if you want to get the latest version of various code.]  Run "astup", which will upgrade any applications via rsync over the Internet from Kristian Kielhofner's site, which has the latest updates to various code bits.  Answer "yes" to the questions (the default answers)  Make sure you run this step before any others, as it will over-write many of the changes listed below.


14) Next, let's get all the extra apps and goodies.  We have to define the second and third partitions on the card, format them, and then run two scripts to put the right data in those partitions.

a) Open your CF card in fdisk with "fdisk /dev/hda" (where hda is your CF card; it might be "hdb" depending on what happened in prior steps.)

Create hda2:
b) Press "n" to make a new partition.
c) Press "p for a primary partition.
d) Press "2" for partition 2.
e) Hit return for the defaults on starting cylinder
f) Enter "+16M" (note the capitalization) as the last cylinder

Create hda3:
g) Press "n" to make a new partition.
h) Press "p for a primary partition.
i) Press "3" for partition 3.
j) Hit return for the defaults on starting cylinder
k) Enter "+7M" (note the capitalization) as the last cylinder

l) Press "w" to save your changes and exit.  Ignore the "device or resource busy" error if you get one.
m) Reboot.  Log back in as root.

n) Run "mke2fs /dev/hda2" and then run "mke2fs /dev/hda3" to format the filesystems.
o) Reboot.  Log back in as root.

p) You should see hda2 and hda3 in the list of filesystems displayed by typing "mount" - the system should have mounted it as /mnt/opt and /mnt/kd respectively.


q) Run the "mkopt" script to download the AstLinuxOpt package to your new /opt partition.  The script will automatically check to ensure that /mnt/opt (the new location of this extended filesystem) is mounted.
r) Umount /dev/hda3 with "umount /mnt/kd", if it is mounted (which should be the case, automatically - make sure you changed ALL the references to /dev/hdaX to /dev/hdbX if you needed to fix things in step 9!)
s) Build the "site-specific" copy of your data on hda3 by issuing the command "genkd /dev/hda3" - this copies all of the files which we'll be modifying into /mnt/kd.  Say "Yes" to the question about creating a KeyDrive.
t) Reboot.

Notes: While you should not need it, the command to format a filesystem is "mke2fs /dev/hda2" as an example.


15) Edit the /kd/rc.conf file.

 - Change these lines to suit:

## System Domainname ##
DOMAIN=bigu.edu
HOSTNAME=poptart

 - Uncomment and change your timezone

TIMEZONE=GMT

(other options would be "America/Los_Angeles", "America/Chicago" or "America/New_York" as examples)


 - Uncomment and edit the IP address, netmask, default gateway, and nameservers of the device for static use (per your site's config)

EXTIP="192.168.25.2"
EXTNM="255.255.255.0"
EXTGW="192.168.25.1"
DNS="192.168.1.1 192.168.1.2 192.168.1.3"

 - Ensure the INTIP and INTNM lines are commented out, otherwise firewalls and other things are started at boot.  This is not the default configuration, so be sure to put a # in front of those two lines.

 - I would suggest rebooting to ensure all this is written and runs correctly before continuing.


16) Time to go to the web interface.  There is a minimal administrative web interface, which can be accessed with HTTPS at the IP address of the external interface, with url /admin.  In other words:  https://10.0.2.3/    The username is "admin" and the initial password is "astlinux".  It's OK that the "DNSMasq Daemon" is down - it is not used.


17) Change the web administrator password.  This is done through the "Setup" menu.


**** From here down, the configurations reference the Asterisk ****
**** configuration.  The UNIX side of things is complete.      ****

18) Edit/create a new file called /mnt/kd/zaptel.conf and insert these lines:

span=1,0,0,esf,b8zs
bchan=1-23
dchan=24
loadzone = us
defaultzone=us


19) Edit /mnt/kd/asterisk/zapata.conf and add these lines to the end of the file:

switchtype = national
signalling = pri_cpe
group = 1
channel => 1-23

These last two steps assumes a "national" signalling method for the PRI, and that all 23 channels are used in a very "vanilla" setup for a PRI.  If you're running some other type of signalling, you'll need to alter this to suit.  If your switch/PBX expects the PRI from the Asterisk device to be "central office" signalling format, change "pri_cpe" to "pri_net".  For more details on configuring the Zaptel portions of Asterisk, please consult the web-based documentation for Asterisk or http://www.voip-info.org/ as this is outside the scope of this document.


20) Configure the sangoma card to be a TDM PRI interface.
  
  a) Run "wancfg".  Note: you may or may not be able to run this application from the console easily due to terminal emulation constraints.  My suggestion is to log into the system via ssh from another machine.

  b) "C"reate a netw configuration file

  c) Select "wanpipe1.conf"

  d) Select from detected cards list

  e) Choose "AFT-A101u SLOT=10..." [etc.]

  f) Use all defaults in "Hardware Configuration" menu; select "Back"
       card type=A101/2
       Physical Medium=T1
  
  g) In "Wanpipe Configuration" menu, select "Protocol"

  h) Select "TDM Voice".   Then go "Back" to "Wanpipe Configuration" menu

  i) select "Interface Setup-->1 Defined"

  j) Select "Interface 1->w1g1" (there are no other options on this page)

  k) In "Interface Configuration" screen, make your screen match this:
         Interface Name=w1g1
         Operation Mode=TDM_VOICE
         TDM Voice Span=1
         Override Asterisk Echo Enable=Yes
         TDM PRI HW-HDLC Timeslot=0 Not Used
         Hardware Echo Cancellation=Yes
         Hardare Echo Cancellation Map=ALL

  l) Go back/exit out of various menus. Answer "Yes" to the question of "Do you want to save wanpipe1.conf?"  Continue exiting out of application.

  m) NOTE: If you have nothing plugged into the WAN port, your console may be unusable due to error messages!  I would suggest plugging in an RJ-45 T1 loopback plug into the device while it is not connected to any T1 equipment to prevent this state.


21) Reboot yet again to make the wanpipe configurations active.


22) Start modifying Asterisk to match what your site requires.  This is a whole different set of example files but the basic configuration is complete and Asterisk should launch correctly at this point with all 23 PRI ports active.



JT's custom notes for Asterisk, which kind 

 - add "usernames" file for seed definitions in /mnt/kd/asterisk/

 - modify /mnt/kd/asterisk.conf for exec options permissions:

[options]
execincludes=yes  

 - Modify modules.conf and add this before the [global] section:

; modules.conf modifications by John Todd (jtodd@tello.com)
; This removes some modules that we just aren't using in the
;  Soekris distribution.  We really don't need to do this, but it
;  makes the memory footprint a little smaller, and hopefully removes
;  more spinning gears that don't need to be spinning.
; 
noload => res_adsi.so
noload => chan_skinny.so
noload => chan_agent.so
noload => chan_mgcp.so
noload => pbx_realtime.so
noload => pbx_ael.so
noload => app_festival.so
noload => app_sms.so          
noload => app_alarmreceiver.so
noload => app_getcpeid.so
noload => app_adsiprog.so         
noload => app_zapras.so               
noload => app_realtime.so
noload => app_voicemail.so 
noload => app_hasnewvoicemail.so
noload => app_queue.so     
noload => format_g729.so              
noload => format_g726.so   
noload => format_g723.so
noload => format_ilbc.so 
noload => codec_lpc10.so
noload => codec_g726.so     
noload => codec_ilbc.so 

 - copy extensions.conf to extensions.conf.orig
 - copy sip.conf to sip.conf.orig
 - copy sip.conf from my test configs with SIP.edu specifics for the SIP.edu load