AstLinux:AUser'sGuide

By:KristianKielhofner ForAstLinuxversion0.2.6 05/14/05

Introduction
WelcometothewonderfulworldofLinux,[Soekris],andAsterisk!In thisdocumentIwillattempttomakethe0.2.6versionofAstLinuxworkforyou (oratleasthelpyoumakethemworkforyou). IfyouhaveexperiencewithAstLinux0.1.xyouknowthatIcouldhave madeitsmaller,cleaner,andeasiertoworkwith.Iknowthattoo.Previous releasesofAstLinuxwereaproofofconceptanexperimenttoseehow viableAsteriskontheSC1100platformwas.Aftermanydownloadsandhappy customersIcantellyouthatitmostcertainlywas.Nowitistimetodoitfor real,anddoitright.WelcometoAstLinux0.2.6! AstLinux0.2hasbeenreworkedfromthegroundupbuiltfromscratch tomakeitsmaller,leaner,andmoreflexible. AstLinux0.2hasthefollowingfeatures(innoorder):

Linuxkernel2.6.11.7 dnsmasq watchdog(busybox) ssmtp cron(busybox) bash busybox(andeverythingwithit...) TFTPserver vsftpdFTPserver mini_httpd(withSSL) PHPinCGImode(patchedforabove) OpenSSH OpenSSL NTP(ntpdate,ntpq,ntpd) syslog(busyboxwithremotelogsupport) vi(frombusybox) tc(kerneltrafficshaping) iptables phpconfiginspiredwebGUI Asterisk(withasterisksoundspackage) AstShape(mywonderfulQoS/trafficshapingscript) rsync nfsutils(kernelmodulesanduserspacetoolsforNFSsupport)

SangomaWANPIPE2.3.21(forusewithA101/102/104/S518) Zaptel ztdummy libpri rppppoe(PPPoEclient) pppd andmany,manymore(downloadtofindout!)

Soyouhaveallofthis(andmuchmore)inyourregularLinuxdistro?I knowthat!Thequestionis,doesyourLinuxdistrorunona32mbcompact flashcard?DoesitallowyoutoruntheentireOSfromreadonlymemory?Can youdownloadandinstallitonaSoekrisNet4801/i586innotimeatall?Ididn't thinkso! Reallythough,AstLinuxismuchmorethanthat.AstLinuxcanalsorun onmosthardware(i586mmxandup).Ihaveincludedagenerici586kernel thatshouldworkwithmostsystems,justnotall.Fornow,Iamfocusingonthe SC1100seriesofSBC's(andtheSoekrisNet4801)inparticular.

Installation
AstLinuxcanbeinstalledbywritingthecompressedimagefiletoa compactflashcardof32megabytesorlarger.Hereishowyoucanwritethe imagefileunderLinux: gunzipc/path/to/astlinux.img.gz>/dev/sda(assumingsdaisyourCFcard) UnderWindows,youcanusetheAstLinuxSetuppackagefrommy websiteatwww.kriscompanies.com.Onceyouhavedownloadedandinstalled it,youwillfindanewProgramsgroupundertheStartMenucalledAstLinux. UnderthismenuyouwillfindseveralentriestowriteimagestoCompactFlash cards.WithyourCFreader/writerconnected(andCFcardinserted),selectone oftheentriesfromthelist.Physdiskwritewillstartandpromptyoutoselecta devicetowritetheimageto.Makesuretoselecttheproperdestinationdisk. Physdiskwritewillnotwritetoanythinglargerthan800mbwithoutspecifically overridingit.USEWITHCAUTION!!! Oncetheimagewriteouthasfinished,press[enter}toclosetheDOS window,safelydetachtheUSBreader/writerandinserttheCFintoyourdevice. Havefun!

Configuration
I'mnotgoingtolietoyou:AstLinuxdoesnotneedanyconfigurationto bootproperlyandrun.Ifyouwouldliketocustomizecertainaspectsof AstLinux,Ihavetriedtoconsolidateasmuchaspossibleintoonefile,rc.conf. FreeBSDpeopleshouldrecognizethisimmediatelybecausethatonefile, rc.conf,getssourcedbyeverystartupscriptintheOS.Ilikethatidea,andI wantedtocontinueit. WhenyouinitiallybootyourmachineandAstLinuxstarts,youwillsee kernelmessagesanddebuginformationscrollbyuntilyouseealoginprompt (ifyouhavetheserialconsoleconnected,thatis).Ifyouwerewatchingclosely, youwouldhavenoticedthattheerrorLEDgoesoffassoonasyoureachthe loginprompt.Thisishowyouknowthatthesystemisreadyifyoudonothave aserialconsoleoranyothermeanstomonitorthesystem.Bydefault,the startupprocessperformsthefollowingtasks:

mountsallfilesystemsin/etc/fstab createsbasicdirectoriesintmpfsfilesystems loadskernelmodulesfortheclockandNatSemiethernetchips bringsupeth0viaDHCP(bydefault,changeinrc.conf) setstheclockviantp(fromrc.conf) generatescrucialsystemfiles:/etc/hosts,etc. startsalloftheexecutablescriptsin/etc/init.d: watchdog,syslog,iptablesfirewall,trafficshaping,dnsmasq,ntpd,sshd, inetd,asterisk,andmini_httpd

Itreallydoesalotmorethanthis,butyougettheidea.Ittriestobe smartaboutthings,forinstance,ifyouspecifyanstaticIPaddressforthe externalinterfaceinrc.confitwillnottrytobringitupwithDHCP,etc. Thisiswherethingsgettricky.CompactFlashhasalimitednumberof read/writecycles.Itisprettyupthere,butIhavehadCF'sdieonmeandit isn'tprettyinwhatisotherwisearocksoliddevice.ThisiswhyIhavechosen toimplementAstLinuxthewaythatIhave. Therecommended(highlyrecommended)wayofusingAstLinuxisto havethebaseOSandprogramsrunoffofa32mb(orlarger)compactflash card.Nothinguserorsitespecificwillbestoredonthisflashcard,andit shouldhardly(ornever)havetobemountedread/write.Thisshouldprolong thelifeoftheCFcardbymanymagnitudes. SohowdoIdowritesonthisthing?Simple:puttheUSBporttowork...I amsurethatmanyofyoufellowgeeksouttherehaveaUSBkeydisk(flash drive)thatyouhaveattachedtoyourkeychain.

TheSoekrisNet4801hasaOHCIUSB1.1portonthebackfaredgeofthe case,pastthepowerconnector.Itseemstoworkprettywellforsmallamounts ofwritesincombinationwithaUSBkeydiskforstoringthingslikevoicemail, Asteriskconfigs,AstLinuxconfigs,DHCPleases,etc.Iwillshowyouhowto utlilizethisportandthetoolsatyourdisposal: Step1:OnceyouhaveinstalledAstLinuxandithasbooted,logintothesystem withtheusernamerootandthepasswordastlinux(noquotes). Step2:Youshouldnowhavealoginprompt.InsertyourUSBkeydiskintothe USBconnectorontheSoekris.YoushouldseesomeweirdSCSIdiskstuffscroll byontheconsole.Pressenterafewtimestoseeyourpromptagain. THENEXTSTEPWILLDESTROYANYTHINGTHATISONYOURUSBFLASH DRIVE.YESISAIDDESTROY!BACKITUP! Step3:Typegenkdagainwithnoquotes.Followalong. Step4:Reboot.ISAIDREBOOT! Thegenkdscriptwilltakecareofpartioning,formatting,andcopyingthe AstLinuxconfigfilesontoyourUSBkeydisk.Whenyourebootalloftheinit scriptswillseewhatfilesareonthekeydisk.Iftheyarethere,theirrespective softwarepackageswillusethekeydisk.Ifnot,theywillusetheAstLinux defaults.ThisappliestoallofthesoftwarepackagesthatIcouldseepeople wantingtoconfigureoften,aswellasanythingthatneededtobewrittento nonvolatilememorylikevoicemail,etc.Thisisallaccomplishedbyusing symlinks,andusingthemoften.Pleasekeepthisinmindbeforeyoustart manuallymovingfilesaroundandoverwritingthosesymlinks.Theyaredearly important! NOTE:Youcouldjustaseasilyuseanexternalharddrive,internalIDEhard drive,NFSshare,etc.Thismayrequiresometweaking,readonfor information... YoucannowstarttoconfigureyourAstLinuxinstallation.Thesingle magicalconfigurationfilerc.conf,residesat/etc/rc.conf.Onceyoucomplete theprocedureabove,youshouldbeabletoopenthisfileinviandmakeany changesthatyouwant.Itisprettyselfexplanatory,andhopefullyfullof commentstomakeiteasiertounderstand.Ifyoumakeanychangestothisfile, thebestwaytoapplythemisjusttorestart.Iknowthatsomepeopleliketo reportmaduptimesbutIlikemystufftoworkwhenithastocoldboot.Thatis whyIwantyoutorestarttheentiresystem. Asteriskcanbeconfiguredasalways,byeditingthevarious configurationfilesin/etc/asteriskfromtheshell.Orcanit...Ihaveincludeda phpconfiglikeGUI.ItisasimplePHPinterfacetotheAsteriskconfiguration

textfilesthatisaccessiblefromanywebbrowserthatsupportsSSL.Youcan accessitbygoingtotheIPaddress(ontheLANinterface)ofthemachineand usinghttps://[insertiphere].Thedefaultis192.168.101.1,sothefullURLis https://192.168.101.1.Youshouldseesomewarningmessagesaboutthe certificatenotbeingtrusted,notmatchingthesite,havinganIPaddressof 0.0.0.0,etc.That'sokay.WeknowwhotheSoekrisis.Wejustwanttomake surethatthesessionisencrypted.That'swhatthiscertificateaccomplishes. Youwillthenbepromptedforausernameandpassword.Thedefaultis adminandastlinux. PHPNuts:YoucanseehowIcompiledPHPbygoingtohttps://[ipaddress]/ phpinfo.php AdvancedUsage:IknowsomeofyouarewonderingHey,canIusemultiple USBkeydiskstostoredifferentsetsofconfiguration?Theansweris:You knowit!Therearesomecaveats,however: 1) Neverconnectmorethanoneatatimeunlessyouknowwhatyouaredoing. 2) Makesuretoinitializeeachofthemseparatelywithgenkd.Iamnot responsibleifyoudoitsomeotherway. 3) Youstillneedtoreboottochangeconfigurations. Let'ssaythatyouneedtodemothepowerofAsteriskforaclient.Config upanewkeydisk,configureeverything,anddemoaway!Labelthatthing,and repeatfromsteponeforthenextclientuntilyouneedtostartover.Therearea lotofotheruses,butyougettheidea...ALLoftheuserconfigsarestoredon thekeydisk.ThinkofitasapersonalityforAstLinux,likeaSIMcardinaGSM phone. Tomakeotherchangeselsewhereonthefilesystem(includingchanging thepassword),youwillneedtomounttherootfilesystemreadwrite,make yourchanges,andremountthefilesystemreadonly: 1) mountorw,remount/ 2) Makechanges... 3) mountoro,remount/

AstLinuxOpt
Overtime,peoplehaveaskedforfeaturesthateitherjustwon'tfitinthe baseinstall,ormostuserswon'tneedforordinaryoperation.ThisiswhyI createdAstLinuxOpt.AstLinuxOptincludessoftwarethatmanypeoplewill finduseful,including: strace screen

tcpdump Fullzoneinfo(timezones) ncftpput sox(withMP3support) soxmix(withMP3support) GNUnano(easytousetexteditor) racoon&setkeyIKEsupport openvpn(noLZOsupport) opensslbinary AsteriskSoundspackage

TogetAstLinuxOpt,youwillneedtoknowhowtousefdisk.Iwouldlike tomakeiteasier,butunfortunatelyIdon'tknowhowbigyourcompactflash cardis!Currently,IrecommendmakingtheAstLinuxOptpartitionatleast 32mb,butyoucanmakeitasbigorsmallasyouwish,aslongasitislarger thanthesizeofAstLinuxOpt(currently~5mb). Here'swhatyoucandotogetAstLinuxOpt: 1) OpenyourCFcardinfdiskfdisk/dev/hda(wherehdaisyourCFcard) 2) Pressntomakeanewpartition. 3) Presspforaprimarypartition. 4) Press2forpartition2. 5) Presswtosaveyourchangesandexit. 6) Reboot. 7) FromtheGRUBbootmenu,makesurethatyourselectionhas astopt=/dev/hda2onthekernelcommandline. 8) Createthefilesystemon/dev/hda2mke2fs/dev/hda2. 9) Mountitmounttext2/dev/hda2/mnt/opt. 10)Whenthefilesystemhasmounted,runthemkoptscripttodownloadthe AstLinuxOptpackagetoyournewpartition. 11)Done!(Youmaywanttoreboottomakesure,butitisn'tnecessary).

AsteriskOnlyMode
Manypeopledon'twanttousethefirewall,QoS,andDHCPserver featuresofAstLinux.That'sfine.Wheneditingrc.conf,commentouttheINTIF variableandreboot.AstLinuxwillonlyusetheEXTIFinterface,andmany services/daemonswillnotbestarted.SSH,mini_httpd,inetd,andAsteriskwill stillbestarted.

SpecialnotesforGenerici586users
AstLinuxwillbydefaultnotworkwithallofthehardwareoutthere.I havecreatedthisimagetoenableyoutouseAstLinuxonSOMEpchardware.I

haveincludedsupportformostIDEcontrollersandNICs.InorderforAstLinux toworkwithyourhardware,sometweakingmaybeinvolved.OnethingthatI knowyouwillhavetochangeisthemodule(s)thatis/areloadedforyour networkcard(s).Thedefaultfrompreviousversionshaschanged.Whenthe i586imagestartsup,itwilltrytoloadalloftheavailablenetworkmodules. Thisistoinsurethatatleastonenetworkcardisdetected.Ihavetriedthis methodonseveralmachineswithnoproblem,butitisstillagoodideato disable/reorderthemodules.Thefile/etc/rc.modulesisalistofmodulesthat areloadedwhenthesystemboots.Modifythisfiletosuityourneeds: mountorw,remount/ vi/etc/rc.modules mountoro,remount/ Reboot. Yourhardwarewillhavetobesimilartothefollowing: i586mmx+up(AsteriskwilldiewithoutMMX!) ATAController(Intel,AMD,VIA,Nvidia,andgenerics) NIC(e100/eepro100,tulip,e1000,tigon3,3c59x,andmanymore) usbohci,uhci,orehci(prettymuchallofthem) Foranmoreaccurateview,takealookatthemodulesin/lib/modules. YoucannowpassthepathofyourkeydiskontheGRUBcommandline. Similartoabove,whenthesystembootsyoucanmodifytheastkd=variableto changeyourkeydiskdevice.Thegenkdscriptmentionedabovenowalso usesthisvariableandalsoacceptstheoptiontooverridetheastkd=variable.If youwanttouseadeviceotherthantheonespecifiedonthekernelcommand lineforyourkeydisk,allyouhavetodoispassthedevicenameonthe commandlinelikeso: genkd/dev/hda1 ThiswillusethefirstIDEharddiskonthemachineforyourkeydisk. Remembertoselecttherightoptionwhenyoubootyoursystem!

BootingfromUSB
AstLinux0.2.4andlaterprovidesupportforbootingfromUSB(ifthe machine'sBIOSsupportsit).Theonlychangeneededisverysimple.After writingthei586imagetoaUSBflashdrive,settheBIOStobootfromit(USB harddisk).Whenthesystemfirstboots,youhaveafewsecondstochosethe AstLinuxbootoptions.YouwillneedtoselecttheBootfromUSBoption.

Thiswillbesavedasyourdefaultentry. NOTE:Ifyouseeerrorsaboutnotbeingabletomounttherootdevice,thatis normal.Ihadtopatchthekernelsothatitwouldautomaticallyretrytomount therootfilesystemevery1seconduntilsuccessful.Thisisneededbecauseit usuallytakesafewsecondsfortheUSB,usbstorage,andSCSIdiskcodeto detecttheUSBcontrollerandUSBdevice(s). UPDATE:AsofAstLinux0.2.6,thisdoesn'tseemtoworkanymore.Ifanyone knowshowtogeta2.6kerneltobootfromUSB,pleaseletmeknow!

BootingfromCD
AstLinux0.2.4andlaterprovidesupportforbootingfromCD(ifthe machine'sBIOSsupportsit).YouwillneedtodownloadtheISOcdromimage fromwww.kriscompanies.com,andburnittoacdusingcdrecordunder Linux,orNero/RoxiounderWindows.Pleasenotethatjustplacingthisimage onacdisnotsufficienttomakeitwork.Youwillneedtousethecreatecd fromimage(orsimilar)option.AfreeprogramthatdoesthisunderWindows isDVDDecrypter. Whenthecdboots,youwillneedtospecifywhatdeviceyourcdrom driveis.InthefutureIwillbeaddinganautodetectfeature,atwhichtime thiswillnolongerbenecessary.Butfornow,youwillneedtopassthecorrect root=optiontoisolinux.

Upgrading
UpgradinghastraditionallybeenaproblemwithAstLinux.Ihave attemptedtomakeiteasierinthisrelease.Withtheintroductionofakeydisk system,thereisnowaclearseparationbetweenuserdataandtherestofthe system.Thismakesmyupdatescript,astup,easiertouseanddesign.Astup usesrsynctoupdateyoursystemfrommyAstLinuxrepositoriesatkrisk.org. Thefile/etc/astup.exdefinesalistoffilesaredirectoriesthatastupwill nevertouch.Thisincludestheobvious(proc,dev,etc.)aswellasanythingon yourkeydisk(orwhateverismountedat/mnt/kd).ANYTHINGELSEISFAIR GAMETOBEOVERWRITTEN.Uponexecution(withnoarguments)astupwill determinewhichAstLinuxbuildyouarerunning,anddisplayalistoffilesthat willbetransferred/deleted/etc.Ifthisisacceptable,simpletypeyesand astupwillupdateyoursystem.Youwillneedtorebootforsomechangesto apply.Ifyoumakeanychangestoanynonexpectedareaofthesystem,you willneedtoaddthatfile/pathto/etc/astup.ex.Otherwiseyourchangeswill beoverwritten.

Toinsureacompleteupgrade,itisrecommendedthatyourunastup againifyouseeusr/sbin/astupinthelistoffilestobetransferredonthefirst run.Thishelpstomakeyoursystemasconsistentaspossible.

ToDo's
Setupwizard,BRIStuff,VASTLYimprovedwebinterface,betterVPN support,andmore.RemembertokeepcheckingKrisCompanies.comfor updates.

Soyouwantmore...
AstLinuxgottowhereitistodaybecauseoffeedbackfrompeoplelike yourself.Pleasefeelfreetocontactmeviaemailwithfeaturerequestsandbug reports.IwilltrytogetbacktoyouassoonasIcan.Ifyouneedsomefeature orsoftwareadded,Iwillprobablyaddittothenextrelease.Ifyouneed somethingmajordonewithAstLinux,Linux,Asterisk,etc,KrisCompanies specializesinthesetypesofthingsandwewouldbehappytohelpyouout.

Support
WhileIcannotpossiblyhelpeveryonewitheverypossibleproblem,I enjoyhelpingwhoeverIcan.IhavesetupmailinglistssothatanyhelpthatI providepeoplecanbepublictopossiblyhelpothers.Hopefullythenpeople canstarthelpingotherpeople,etc.Themailinglistscanbefoundat: http://lists.kriscompanies.com/

Credits
Portionsofthisworkhavebeensponsoredby1NetTransworld,Inc. Hardwareandbandwidthhavebeengraciouslydonatedby1NetTransworld, Inc.ThanksJon! PortionsofthisworkhavebeensponsoredbytheAviaryGroup.

ContactInformation

KristianKielhofner WWW:http://www.kriscompanies.com DonationsmaybesentviaPayPaltopaypal@krisk.org.Thanks!