GentooLinuxAMD64Handbook

SvenVermeulenAuthor GrantGoodyearAuthor RoyMarplesAuthor DanielRobbinsAuthor ChrisHouserAuthor JerryAlexandratosAuthor SeemantKulleenGentoox86Developer TavisOrmandyGentooAlphaDeveloper JasonHuebelGentooAMD64Developer GuyMartinGentooHPPAdeveloper PieterVandenAbeeleGentooPPCdeveloper JoeKallarGentooSPARCdeveloper JohnP.DavisEditor PierreHenriJondotEditor EricStockbridgeEditor RajivManglaniEditor JungminSeoEditor StoyanZhekovEditor JaredHudsonEditor ColinMoreyEditor JorgePauloEditor CarlAndersonEditor JonPortnoyEditor ZackGilburdEditor JackMorganEditor BennyChuangEditor ErwinEditor JoshuaKinardEditor TobiasScherbaumEditor XavierNeysEditor JoshuaSaddlerEditor GeraldJ.NormandinJr.Reviewer DonnieBerkholzReviewer KenNowackReviewer LarsWeilerContributor PageupdatedJuly8,2012 Content: InstallingGentoo InthispartyoulearnhowtoinstallGentooonyoursystem. 1. AbouttheGentooLinuxInstallation Thischapterintroducesyoutotheinstallationapproachdocumentedinthishandbook. 2. ChoosingtheRightInstallationMedium YoucaninstallGentooinmanyways.ThischapterexplainshowtoinstallGentoousingtheminimal InstallationCD. 3. ConfiguringyourNetwork Tobeabletodownloadthelatestsourcecode,youwillneedtosetupnetworking. 4. PreparingtheDisks TobeabletoinstallGentoo,youmustcreatethenecessarypartitions.Thischapterdescribeshowto partitionadiskforfutureusage. 5. InstallingtheGentooInstallationFiles Gentooinstallsworkthroughastage3archive.Inthischapterwedescribehowyouextractthestage3 archiveandconfigurePortage.

6. InstallingtheGentooBaseSystem Afterinstallingandconfiguringastage3,theeventualresultisthatyouhaveaGentoobasesystemat yourdisposal.Thischapterdescribeshowtoprogresstothatstate. 7. ConfiguringtheKernel TheLinuxkernelisthecoreofeverydistribution.Thischapterexplainshowtoconfigureyourkernel. 8. ConfiguringyourSystem Youneedtoeditsomeimportantconfigurationfiles.Inthischapteryoureceiveanoverviewofthese filesandanexplanationonhowtoproceed. 9. InstallingNecessarySystemTools Inthischapterwehelpyouchooseandinstallsomeimportanttools. 10. ConfiguringtheBootloader Inthischapterwe'lldescribetheGRUBbootloaderandstepyouthroughtheprocessofconfiguring GRUBtoyourneeds. 11. FinalizingyourGentooInstallation You'realmostdone.We'lljustcreateone(ormore)usersforyoursystem. 12. Wheretogofromhere? NowyouhaveyourGentoosystem,butwhat'snext? WorkingwithGentoo LearnhowtoworkwithGentoo:installingsoftware,alteringvariables,changingPortagebehaviouretc. 1. APortageIntroduction Thischapterexplainsthe"simple"stepsauserdefinitelyneedstoknowtomaintainthesoftwareon hissystem. 2. USEflags USEflagsareaveryimportantaspectofGentoo.Inthischapter,youlearntoworkwithUSEflags andunderstandhowUSEflagsinteractwithyoursystem. 3. PortageFeatures DiscoverthefeaturesPortagehas,suchassupportfordistributedcompiling,ccacheandmore. 4. Initscripts Gentoousesaspecialinitscriptformatwhich,amongstotherfeatures,allowsdependencydriven decisionsandvirtualinitscripts.Thischapterexplainsalltheseaspectsandexplainshowtodealwith thesescripts. 5. EnvironmentVariables WithGentooyoucaneasilymanagetheenvironmentvariablesforyoursystem.Thischapterexplains howyoudothat,andalsodescribesfrequentlyusedvariables. WorkingwithPortage "WorkingwithPortage"providesanindepthcoverageofPortage,Gentoo'sSoftwareManagementTool. 1. FilesandDirectories OnceyouwanttoknowPortageindepthyouneedtoknowwhereitstoresitsfilesanddata. 2. ConfiguringthroughVariables Portageiscompletelyconfigurablethroughvariousvariablesyoucansetintheconfigurationfileoras environmentvariable. 3. MixingSoftwareBranches Gentooprovidessoftwareseparatedinseveralbranches,dependingonstabilityandarchitectural support."MixingSoftwareBranches"informyouhowthesebranchescanbeconfiguredandhowyou canoverridethisseparationindividually. 4. AdditionalPortageTools PortagecomeswithafewextratoolsthatmightmakeyourGentooexperienceevenbetter.Readon todiscoverhowtousedispatchconfandothertools. 5. DivertingfromtheOfficialTree "DivertingfromtheOfficialTree"givesyousometipsandtricksonhowtouseyourownPortagetree, howtosynchroniseonlythecategoriesyouwant,injectpackagesandmore. 6. AdvancedPortageFeatures Astimesgoesby,Portageevolvesandmaturesfurtherandfurther.Additionalfeaturesare continuouslybeingputinmanyoftheseareonlyofusebymoreadvancedusers.Thischapterwill

gointomoredetailofthesespecificfeatures. GentooNetworkConfiguration AcomprehensiveguidetoNetworkinginGentoo. 1. GettingStarted Aguidetoquicklygetyournetworkinterfaceupandrunninginmostcommonenvironments. 2. AdvancedConfiguration Herewelearnabouthowtheconfigurationworksyouneedtoknowthisbeforewelearnabout modularnetworking. 3. ModularNetworking GentooprovidesyouflexiblenetworkinghereyouaretoldaboutchoosingdifferentDHCPclients, settingupbonding,bridging,VLANsandmore. 4. WirelessNetworking Wirelessconfigurationcanbetricky.Hopefullywe'llgetyouworking! 5. AddingFunctionality Ifyou'refeelingadventurous,youcanaddyourownfunctionstonetworking. 6. NetworkManagement Forlaptopusersorpeoplewhomovetheircomputerarounddifferentnetworks.

A.InstallingGentoo
1.AbouttheGentooLinuxInstallation
1.a.Introduction Welcome!
Firstofall,welcometoGentoo.Youareabouttoentertheworldofchoicesandperformance.Gentooisallabout choices.WheninstallingGentoo,thisismadecleartoyouseveraltimesyoucanchoosehowmuchyouwantto compileyourself,howtoinstallGentoo,whatsystemloggeryouwant,etc. Gentooisafast,modernmetadistributionwithacleanandflexibledesign.Gentooisbuiltaroundfreesoftwareand doesn'thidefromitsuserswhatisbeneaththehood.Portage,thepackagemaintenancesystemwhichGentoo uses,iswritteninPython,meaningyoucaneasilyviewandmodifythesourcecode.Gentoo'spackagingsystem usessourcecode(althoughsupportforprecompiledpackagesisincludedtoo)andconfiguringGentoohappens throughregulartextfiles.Inotherwords,opennesseverywhere. ItisveryimportantthatyouunderstandthatchoicesarewhatmakesGentoorun.Wetrynottoforceyouonto anythingyoudon'tlike.Ifyoufeellikewedo,pleasebugreportit.

HowistheInstallationStructured?
TheGentooInstallationcanbeseenasa10stepprocedure,correspondingtochapters211.Everystepresultsin acertainstate: Afterstep1,youareinaworkingenvironmentreadytoinstallGentoo Afterstep2,yourinternetconnectionisreadytoinstallGentoo Afterstep3,yourharddisksareinitializedtohouseyourGentooinstallation Afterstep4,yourinstallationenvironmentispreparedandyouarereadytochrootintothenewenvironment Afterstep5,corepackages,whicharethesameonallGentooinstallations,areinstalled Afterstep6,youhavecompiledyourLinuxkernel Afterstep7,youhavewrittenmostofyourGentoosystemconfigurationfiles Afterstep8,necessarysystemtools(whichyoucanchoosefromanicelist)areinstalled Afterstep9,yourchoiceofbootloaderhasbeeninstalledandconfiguredandyouareloggedinintoyournew Gentooinstallation Afterstep10,yourGentooLinuxenvironmentisreadytobeexplored

Whenyouaregivenacertainchoice,wetryourbesttoexplainwhattheprosandconsare.Wewillcontinuethen withadefaultchoice,identifiedby"Default:"inthetitle.Theotherpossibilitiesaremarkedby"Alternative:".Do notthinkthatthedefaultiswhatwerecommend.Itishoweverwhatwebelievemostuserswilluse. Sometimesyoucanpursueanoptionalstep.Suchstepsaremarkedas"Optional:"andarethereforenotneeded toinstallGentoo.However,someoptionalstepsaredependentonapreviousdecisionyoumade.Wewillinform youwhenthishappens,bothwhenyoumakethedecision,andrightbeforetheoptionalstepisdescribed.

WhataremyOptions?
YoucaninstallGentooinmanydifferentways.YoucandownloadandinstallfromoneofourInstallationCDs,from adistributionalreadyinstalled,fromanonGentoobootableCD(suchasKnoppix),fromanetbootedenvironment, fromarescuefloppy,etc. ThisdocumentcoverstheinstallationusingaGentooInstallationCDor,incertaincases,netbooting.This installationassumesthatyouwanttoinstallthelatestavailableversionofeachpackage.
Note:Forhelpontheotherinstallationapproaches,includingusingnonGentooCDs,pleasereadourAlternativeInstallation Guide.

Ifyouwanttoperformanetworklessinstallation,youshouldreadtheGentoo2008.0Handbookswhichcontainthe installationinstructionsforanetworklessenvironment. Alsonotethat,ifyouplanonusingGRP(theGentooReferencePlatform,acollectionofprebuiltpackagesmeant forimmediateuseafteraGentooinstallation),youmustfollowtheinstructionsintheGentoo2008.0Handbooks. WealsoprovideaGentooInstallationTips&Tricksdocumentthatmightbeusefultoreadaswell.Ifyouarean experiencedGentoouserandjustneedabriefinstallationchecklist,feelfreetouseourQuickInstallationGuide availablefromourDocumentationResourcesifyourarchitecturehassuchadocumentavailable. Youalsohaveseveralpossibilities:youcancompileyourentiresystemfromscratchoruseaprebuiltenvironment tohaveyourGentooenvironmentupandrunninginnotime.Andofcourseyouhaveintermediatesolutionsin whichyoudon'tcompileeverythingbutstartfromasemireadysystem.

Troubles?
Ifyoufindaproblemintheinstallation(orintheinstallationdocumentation),pleasevisitourbugtrackingsystem andcheckifthebugisknown.Ifnot,pleasecreateabugreportforitsowecantakecareofit.Donotbeafraidof thedeveloperswhoareassignedto(your)bugstheygenerallydon'teatpeople. Notethoughthat,althoughthedocumentyouarenowreadingisarchitecturespecific,itwillcontainreferencesto otherarchitecturesaswell.ThisisduetothefactthatlargepartsoftheGentooHandbookusesourcecodethatis commonforallarchitectures(toavoidduplicationofeffortsandstarvationofdevelopmentresources).Wewilltryto keepthistoaminimumtoavoidconfusion. Ifyouareuncertainiftheproblemisauserproblem(someerroryoumadedespitehavingreadthedocumentation carefully)orasoftwareproblem(someerrorwemadedespitehavingtestedtheinstallation/documentationcarefully) youarefreetojoin#gentooonirc.freenode.net.Ofcourse,youarewelcomeotherwisetoo:) IfyouhaveaquestionregardingGentoo,checkoutourFrequentlyAskedQuestions,availablefromtheGentoo Documentation.YoucanalsoviewtheFAQsonourforums.Ifyoucan'tfindtheanswerthereaskon#gentoo,our IRCchannelonirc.freenode.net.Yes,severalofusarefreakswhositonIRC:)

2.ChoosingtheRightInstallationMedium
2.a.HardwareRequirements Introduction
Beforewestart,wefirstlistwhathardwarerequirementsyouneedtosuccessfullyinstallGentooonyourbox.

HardwareRequirements

MinimalCD CPU Memory Diskspace Swapspace 256MB 2.5GB(excludingswapspace) Atleast256MB

LiveCD 512MB

AnyAMD64CPUorEM64TCPU(Core2Duo&QuadprocessorsareEM64T)

YoushouldchecktheGentooAMD64ProjectPagebeforeproceeding.

2.b.TheGentooInstallationCDs Introduction
TheGentooInstallationCDsarebootableCDswhichcontainaselfsustainedGentooenvironment.Theyallowyou tobootLinuxfromtheCD.Duringthebootprocessyourhardwareisdetectedandtheappropriatedriversare loaded.TheyaremaintainedbyGentoodevelopers. AllInstallationCDsallowyoutoboot,setupnetworking,initializeyourpartitionsandstartinstallingGentoofrom theInternet.

GentooMinimalInstallationCD
TheMinimalInstallationCDiscalledi s a l a d 4 m n m l < e e s > i o n t l m 6 i i a r l a e . s andtakesuparound150 MBofdiskspace.YoucanusethisInstallationCDtoinstallGentoo,butonlywithaworkingInternetconnection.

GentooLinuxLiveDVDs
Every6months(giveortake),aspecialDVDiscraftedbytheGentooTenprojectwhichcanbeusedtoinstall Gentoowithtoo.TheinstructionsfurtherdownthischaptertargettheMinimalInstallationCDssomightbeabit different.However,theLiveDVD(oranyotherbootableLinuxenvironment)supportsgettingarootpromptbyjust invokings d u u o s ors d i u o onaterminal.

TheStage3Tarball
Astage3tarballisanarchivecontainingaminimalGentooenvironment,suitabletocontinuetheGentooinstallation usingtheinstructionsinthismanual.Previously,theGentooHandbookdescribedtheinstallationusingoneofthree stagetarballs.WhileGentoostilloffersstage1andstage2tarballs,theofficialinstallationmethodusesthestage3 tarball.IfyouareinterestedinperformingaGentooinstallationusingastage1orstage2tarball,pleasereadthe GentooFAQonHowdoIInstallGentooUsingaStage1orStage2Tarball? Stage3tarballscanbedownloadedfromr l a e / m 6 / u o u l s c r e t s a e / e e s s a d 4 a t b i d / u r n t g 3 onanyofthe OfficialGentooMirrorsandarenotprovidedontheLiveCD.

2.c.Download,BurnandBootaGentooInstallationCD DownloadingandBurningtheInstallationCDs
YouhavechosentouseaGentooInstallationCD.We'llfirststartbydownloadingandburningthechosen InstallationCD.WepreviouslydiscussedtheseveralavailableInstallationCDs,butwherecanyoufindthem? YoucandownloadanyoftheInstallationCDsfromoneofourmirrors.TheInstallationCDsarelocatedinthe r l a e / m 6 / u o u l s c r e t i o directory. eessad4atbid/urns/ Insidethatdirectoryyou'llfindISOfiles.ThosearefullCDimageswhichyoucanwriteonaCDR. Incaseyouwonderifyourdownloadedfileiscorruptedornot,youcancheckitsMD5checksumandcompareit withtheMD5checksumweprovide(suchasi s a l a d 4 m n m l < e e s > i o D G S S n t l m 6 i i a r l a e . s . I E T ).Youcan checktheMD5checksumwiththem 5 u toolunderLinux/Unixormd5sumforWindows. dsm AnotherwaytocheckthevalidityofthedownloadedfileistouseGnuPGtoverifythecryptographicsignaturethat weprovide(thefileendingwith. s ).Downloadthesignaturefileandobtainthepublickeyswhosekeyidscanbe ac foundonthereleaseengineeringprojectsite.

CodeListing3.1:Obtainingthepublickey (.usiuetekyiswthsetoenterlaeegneigst.) ..Sbttthedihtoemnindoheesniernie.. $ggkyevrsbesppntrces9DB6D8901025 pesreuky.g.eevky68FD21217708

Nowverifythesignature:
CodeListing3.2:Verifythefiles (eiytecytgahcsgaue Vrfhrporpiintr) $ggvrfdwlaes.IET.s> peiy<onoddioDGSSac (eiyteceku) Vrfhhcsm $sasmdwlaes.IET.s> h1uc<onoddioDGSSac

ToburnthedownloadedISO(s),youhavetoselectrawburning.Howyoudothisishighlyprogramdependent.We willdiscussc r c r andK B deod 3 heremoreinformationcanbefoundinourGentooFAQ. Withcdrecord,yousimplytypec r c r e = d v h c < o n o d d i o f l > d e o d d v / e / d d w l a e s i e (replace / e / d withyourCDRWdrive'sdevicepath). dvhc WithK3B,selectT o s u n C m g .ThenyoucanlocateyourISOfilewithinthe'ImagetoBurn' o l >B r D I a e area.FinallyclickS a t tr.

BootingtheInstallationCD
OnceyouhaveburntyourinstallationCD,itistimetobootit.RemoveallCDsfromyourCDdrives,rebootyour systemandentertheBIOS.ThisisusuallydonebyhittingDEL,F1orESC,dependingonyourBIOS.Insidethe BIOS,changethebootordersothattheCDROMistriedbeforetheharddisk.Thisisoftenfoundunder"CMOS Setup".Ifyoudon'tdothis,yoursystemwilljustrebootfromtheharddisk,ignoringtheCDROM. NowplacetheinstallationCDintheCDROMdriveandreboot.Youshouldseeabootprompt.Atthisscreen,you canhitEntertobeginthebootprocesswiththedefaultbootoptions,orboottheInstallationCDwithcustomboot optionsbyspecifyingakernelfollowedbybootoptionsandthenhittingEnter. Whenthebootpromptisshown,yougettheoptionofdisplayingtheavailablekernels(F )andbootoptions(F ).If 1 2 youmakenoselectionwithin20seconds(eitherdisplayinginformationorusingakernel)thentheLiveCDwillfall backtobootingfromdisk.Thisallowsinstallationstorebootandtryouttheirinstalledenvironmentwithouttheneed toremovetheCDfromthetray(somethingwellappreciatedforremoteinstallations). Nowwementionedspecifyingakernel.OnourInstallationCDs,weprovideseveralkernels.Thedefaultoneis g n o .Otherkernelsareforspecifichardwareneedsandthe o b eto n f variantswhichdisableframebuffer. Belowyou'llfindashortoverviewontheavailablekernels:
Kernel gentoo gentoonofb memtest86 Description DefaultkernelwithsupportforK8CPUS(includingNUMAsupport)andEM64TCPUs Sameasg n o butwithoutframebuffersupport eto TestyourlocalRAMforerrors

Youcanalsoprovidekerneloptions.Theyrepresentoptionalsettingsyoucan(de)activateatwill. Hardwareoptions: acpi=on ThisloadssupportforACPIandalsocausestheacpiddaemontobestartedbytheCDonboot.Thisisonly neededifyoursystemrequiresACPItofunctionproperly.ThisisnotrequiredforHyperthreadingsupport. acpi=off CompletelydisablesACPI.ThisisusefulonsomeoldersystemsandisalsoarequirementforusingAPM. ThiswilldisableanyHyperthreadingsupportofyourprocessor. console=X ThissetsupserialconsoleaccessfortheCD.Thefirstoptionisthedevice,usuallyttyS0onx86,followedby anyconnectionoptions,whicharecommaseparated.Thedefaultoptionsare9600,8,n,1. dmraid=X ThisallowsforpassingoptionstothedevicemapperRAIDsubsystem.Optionsshouldbeencapsulatedin

quotes. doapm ThisloadsAPMdriversupport.Thisrequiresyoutoalsouseacpi=off. dopcmcia ThisloadssupportforPCMCIAandCardbushardwareandalsocausesthepcmciacardmgrtobestartedby theCDonboot.ThisisonlyrequiredwhenbootingfromPCMCIA/Cardbusdevices. doscsi ThisloadssupportformostSCSIcontrollers.ThisisalsoarequirementforbootingmostUSBdevices,as theyusetheSCSIsubsystemofthekernel. sda=stroke ThisallowsyoutopartitionthewholeharddiskevenwhenyourBIOSisunabletohandlelargedisks.This optionisonlyusedonmachineswithanolderBIOS.Replacesdawiththedevicethatrequiresthisoption. ide=nodma ThisforcesthedisablingofDMAinthekernelandisrequiredbysomeIDEchipsetsandalsobysome CDROMdrives.IfyoursystemishavingtroublereadingfromyourIDECDROM,trythisoption.Thisalso disablesthedefaulthdparmsettingsfrombeingexecuted. noapic ThisdisablestheAdvancedProgrammableInterruptControllerthatispresentonnewermotherboards.Ithas beenknowntocausesomeproblemsonolderhardware. nodetect ThisdisablesalloftheautodetectiondonebytheCD,includingdeviceautodetectionandDHCPprobing. ThisisusefulfordoingdebuggingofafailingCDordriver. nodhcp ThisdisablesDHCPprobingondetectednetworkcards.Thisisusefulonnetworkswithonlystatic addresses. nodmraid DisablessupportfordevicemapperRAID,suchasthatusedforonboardIDE/SATARAIDcontrollers. nofirewire ThisdisablestheloadingofFirewiremodules.ThisshouldonlybenecessaryifyourFirewirehardwareis causingaproblemwithbootingtheCD. nogpm Thisdisablesgpmconsolemousesupport. nohotplug Thisdisablestheloadingofthehotplugandcoldpluginitscriptsatboot.Thisisusefulfordoingdebuggingof afailingCDordriver. nokeymap ThisdisablesthekeymapselectionusedtoselectnonUSkeyboardlayouts. nolapic ThisdisablesthelocalAPIConUniprocessorkernels. nosata ThisdisablestheloadingofSerialATAmodules.Thisisusedifyoursystemishavingproblemswiththe SATAsubsystem. nosmp ThisdisablesSMP,orSymmetricMultiprocessing,onSMPenabledkernels.Thisisusefulfordebugging SMPrelatedissueswithcertaindriversandmotherboards. nosound Thisdisablessoundsupportandvolumesetting.Thisisusefulforsystemswheresoundsupportcauses problems. nousb ThisdisablestheautoloadingofUSBmodules.ThisisusefulfordebuggingUSBissues. slowusb ThisaddssomeextrapausesintothebootprocessforslowUSBCDROMs,likeintheIBMBladeCenter. Volume/DeviceManagement: dolvm ThisenablessupportforLinux'sLogicalVolumeManagement. Otheroptions: debug

Enablesdebuggingcode.Thismightgetmessy,asitdisplaysalotofdatatothescreen. docache ThiscachestheentireruntimeportionoftheCDintoRAM,whichallowsyoutoumount/mnt/cdromand mountanotherCDROM.ThisoptionrequiresthatyouhaveatleasttwiceasmuchavailableRAMasthesize oftheCD. doload=X Thiscausestheinitialramdisktoloadanymodulelisted,aswellasdependencies.ReplaceXwiththe modulename. Multiplemodulescanbespecifiedbyacommaseparatedlist. dosshd Startssshdonboot,whichisusefulforunattendedinstalls. passwd=foo Setswhateverfollowstheequalsastherootpassword,whichisrequiredfordosshdsincewescramblethe rootpassword. noload=X Thiscausestheinitialramdisktoskiptheloadingofaspecificmodulethatmaybecausingaproblem. Syntaxmatchesthatofdoload. nonfs Disablesthestartingofportmap/nfsmountonboot. nox ThiscausesanXenabledLiveCDtonotautomaticallystartX,butrather,todroptothecommandline instead. scandelay ThiscausestheCDtopausefor10secondsduringcertainportionsthebootprocesstoallowfordevicesthat areslowtoinitializetobereadyforuse. scandelay=X Thisallowsyoutospecifyagivendelay,inseconds,tobeaddedtocertainportionsofthebootprocessto allowfordevicesthatareslowtoinitializetobereadyforuse.ReplaceXwiththenumberofsecondsto pause.
Note:TheCDwillcheckfor"no*"optionsbefore"do*"options,sothatyoucanoverrideanyoptionintheexactorderyouspecify.

NowbootyourCD,selectakernel(ifyouarenothappywiththedefaultg n o kernel)andbootoptions.Asan eto example,weshowyouhowtoboottheg n o kernel,withd p m i askernelparameters: eto occa

CodeListing3.3:BootinganInstallationCD bo:gnoocca otetodpmi

Youwillthenbegreetedwithabootscreenandprogressbar.IfyouareinstallingGentooonasystemwithanon USkeyboard,makesureyouimmediatelypressAltF1toswitchtoverbosemodeandfollowtheprompt.Ifno selectionismadein10secondsthedefault(USkeyboard)willbeacceptedandthebootprocesswillcontinue. Oncethebootprocesscompletes,youwillbeautomaticallyloggedintothe"Live"GentooLinuxas"root",the superuser.Youshouldhavearoot("#")promptonthecurrentconsoleandcanalsoswitchtootherconsolesby pressingAltF2,AltF3andAltF4.GetbacktotheoneyoustartedonbypressingAltF1. NowcontinuewithExtraHardwareConfiguration.

ExtraHardwareConfiguration
WhentheInstallationCDboots,ittriestodetectallyourhardwaredevicesandloadstheappropriatekernel modulestosupportyourhardware.Inthevastmajorityofcases,itdoesaverygoodjob.However,insomecasesit maynotautoloadthekernelmodulesyouneed.IfthePCIautodetectionmissedsomeofyoursystem'shardware, youwillhavetoloadtheappropriatekernelmodulesmanually. Inthenextexamplewetrytoloadthe8 3 t o 1 9 o module(supportforcertainkindsofnetworkinterfaces):
CodeListing3.4:Loadingkernelmodules #mdrb19o opoe83to

Optional:UserAccounts

Ifyouplanongivingotherpeopleaccesstoyourinstallationenvironmentoryouwanttochatusingi s i r s without rootprivileges(forsecurityreasons),youneedtocreatethenecessaryuseraccountsandchangetherootpassword. Tochangetherootpassword,usethep s w utility: asd

CodeListing3.5:Changingtherootpassword #psw asd Nwpswr:(neornwpswr) easodEtryueasod RneasodRneorpswr) eetrpswr:(eetryuasod

Tocreateauseraccount,wefirstentertheircredentials,followedbyitspassword.Weuseu e a d s r d andp s w asd forthesetasks.Inthenextexample,wecreateausercalled"john".

CodeListing3.6:Creatingauseraccount #ueadGuesjh srdmsron #pswon asdjh Nwpswr:(neonspswr) easodEtrjh'asod RneasodRneonspswr) eetrpswr:(eetrjh'asod

Youcanchangeyouruseridfromroottothenewlycreateduserbyusings : u
CodeListing3.7:Changinguserid #son ujh

Optional:ViewingDocumentationwhileInstalling
IfyouwanttoviewtheGentooHandbookduringtheinstallation,makesureyouhavecreatedauseraccount(see Optional:UserAccounts).ThenpressA t F togotoanewterminal. l2 Youcanviewthehandbookusingl n s i k ,onceyouhavecompletedtheConfiguringyourNetworkchapter (otherwiseyouwon'tbeabletogoontheInternettoviewthedocument):
CodeListing3.8:ViewingtheOnlineDocumentation #lnsht:/w.etoogdce/adokhnbom6.m iktp/wwgno.r/o/nhnbo/adokad4xl

YoucangobacktoyouroriginalterminalbypressingA t F . l1

Optional:StartingtheSSHDaemon
IfyouwanttoallowotheruserstoaccessyourcomputerduringtheGentooinstallation(perhapsbecausethose usersaregoingtohelpyouinstallGentoo,orevendoitforyou),youneedtocreateauseraccountforthemand perhapsevenprovidethemwithyourrootpassword(onlydothatifyoufullytrustthatuser). TofireuptheSSHdaemon,executethefollowingcommand:
CodeListing3.9:StartingtheSSHdaemon #/t/ntdshtr ecii./sdsat

Tobeabletousesshd,youfirstneedtosetupyournetworking.ContinuewiththechapteronConfiguringyour Network.

3.ConfiguringyourNetwork
3.a.AutomaticNetworkDetection Maybeitjustworks?
IfyoursystemispluggedintoanEthernetnetworkwithaDHCPserver,itisverylikelythatyournetworking configurationhasalreadybeensetupautomaticallyforyou.Ifso,youshouldbeabletotakeadvantageofthe manyincludednetworkawarecommandsontheInstallationCDsuchass h c ,p n ,i s i g t s ,s p i g r s ,w e and

lns i k ,amongothers. Ifnetworkinghasbeenconfiguredforyou,the/ b n i c n i commandshouldlistsomenetworkinterfaces si/fofg besideslo,suchaseth0:

CodeListing1.1:/sbin/ifconfigforaworkingnetworkconfiguration #/bnicni si/fofg (.) .. ehLnna:tentWdr0:0B:F6:A t0ikecpEhreHad05:A8:17 iedr121802cs:9.6..5Ms:5.5.5. ntad:9.6..Bat1218025ak2525250 ie6ad:f8:5:af67/0SoeLn ntdre0:0b8:1a1cp:ik URACSUNNUTCSMU10Mti: PBODATRNIGMLIATT:50erc1 Rakt:489ros0dopd0oern:rm: Xpces1972err:rpe:vrus0fae0 Takt:248ros0dopd0oern:are: Xpces1890err:rpe:vrus0crir0 cliin:94tqeee:0 olsos18xuuln10 Rye:8611431M)Xbts13538(1.b Xbts45925(6.bTye:2918182M) Itrut1aeades0e0 nerp:1Bsdrs:x80

Optional:ConfigureanyProxies
IfyouaccesstheInternetthroughaproxy,youmightneedtosetupproxyinformationduringtheinstallation.Itis veryeasytodefineaproxy:youjustneedtodefineavariablewhichcontainstheproxyserverinformation. Inmostcases,youcanjustdefinethevariablesusingtheserverhostname.Asanexample,weassumetheproxyis calledp o y g n o . r andtheportis8 8 . rx.etoog 00
CodeListing1.2:Definingproxyservers (ftepoyflesHTrfi) IhrxitrTPtafc #eprtppoy"tp/poygno.r:00 xotht_rx=ht:/rx.etoog88" (ftepoyflesFPtafc IhrxitrTrfi) #eprt_rx=fp/poygno.r:00 xotfppoy"t:/rx.etoog88" (ftepoyflesRYCtafc IhrxitrSNrfi) #eprSN_RX=poygno.r:00 xotRYCPOY"rx.etoog88"

Ifyourproxyrequiresausernameandpassword,youshouldusethefollowingsyntaxforthevariable:
CodeListing1.3:Addingusername/passwordtotheproxyvariable ht:/sraepswr@rx.etoog88 tp/uenm:asodpoygno.r:00

TestingtheNetwork
YoumaywanttotrypingingyourISP'sDNSserver(foundin/ t / e o v c n )andaWebsiteofyourchoice, ecrsl.of justtomakesurethatyourpacketsarereachingthenet,DNSnameresolutionisworkingcorrectly,etc.
CodeListing1.4:Furthernetworktesting #pnc3wwgno.r igw.etoog

Ifyouarenowabletouseyournetwork,youcanskiptherestofthissectionandcontinuewithPreparingtheDisks. Ifnot,readon.

3.b.AutomaticNetworkConfiguration
Ifthenetworkdoesn'tworkimmediately,someinstallationmediaallowyoutousen t s t p e e u (forregularor wirelessnetworks),p p e s t p p o e u (forADSLusers)orp t (forPPTPusersavailableonx86,amd64,alpha, pp ppcandppc64). Ifyourinstallationmediumdoesnotcontainanyofthesetoolsoryournetworkdoesn'tfunctionyet,continuewith ManualNetworkConfiguration. RegularEthernetusersshouldcontinuewithDefault:Usingnetsetup

ADSLusersshouldcontinuewithAlternative:UsingPPP PPTPusersshouldcontinuewithAlternative:UsingPPTP

Default:Usingnetsetup
Thesimplestwaytosetupnetworkingifitdidn'tgetconfiguredautomaticallyistorunthen t s t p e e u script:
CodeListing2.1:Runningthenetsetupscript #ntstpeh eeut0

ntstp e e u willaskyousomequestionsaboutyournetworkenvironment.Whenallisdone,youshouldhavea workingnetworkconnection.Testyournetworkconnectionasstatedbefore.Ifthetestsarepositive, congratulations!YouarenowreadytoinstallGentoo.SkiptherestofthissectionandcontinuewithPreparingthe Disks. Ifyournetworkstilldoesn'twork,continuewithManualNetworkConfiguration.

Alternative:UsingPPP
AssumingyouneedPPPoEtoconnecttotheinternet,theInstallationCD(anyversion)hasmadethingseasyfor youbyincludingp p p .Usetheprovidedp p e s t p p o e u scripttoconfigureyourconnection.Youwillbeprompted fortheethernetdevicethatisconnectedtoyouradslmodem,yourusernameandpassword,theIPsofyourDNS serversandifyouneedabasicfirewallornot.
CodeListing2.2:Usingppp #ppestp poeu #ppesat potr

Ifsomethinggoeswrong,doublecheckthatyoucorrectlytypedyourusernameandpasswordbylookingat / t / p / a e r t or/ t / p / h p s c e s ecppppsces e c p p c a e r t andmakesureyouareusingtherightethernet device.Ifyourethernetdevicedoesn'texist,youwillhavetoloadtheappropriatenetworkmodules.Inthatcaseyou shouldcontinuewithManualNetworkConfigurationasweexplainhowtoloadtheappropriatenetworkmodules there. Ifeverythingworked,continuewithPreparingtheDisks.

Alternative:UsingPPTP
IfyouneedPPTPsupport,youcanusep t c i n whichisprovidedbyourInstallationCDs.Butfirstyouneed pplet tomakesurethatyourconfigurationiscorrect.Edit/ t / p / a e r t or/ t / p / h p s c e s ecppppsces e c p p c a e r t so itcontainsthecorrectusername/passwordcombination:
CodeListing2.3:Editing/etc/ppp/chapsecrets #nnw/t/p/hpsces aoecppcaert

Thenadjust/ t / p / p i n . p p e c p p o t o s p t ifnecessary:
CodeListing2.4:Editing/etc/ppp/options.pptp #nnw/t/p/pin.pp aoecppotospt

Whenallthatisdone,justrunp t (alongwiththeoptionsyoucouldn'tsetino t o s p t )toconnectthe pp pin.pp server:

CodeListing2.5:Connectiontoadialinserver #ptsrep pp<evri>

NowcontinuewithPreparingtheDisks.

3.c.ManualNetworkConfiguration

LoadingtheAppropriateNetworkModules
WhentheInstallationCDboots,ittriestodetectallyourhardwaredevicesandloadstheappropriatekernel modules(drivers)tosupportyourhardware.Inthevastmajorityofcases,itdoesaverygoodjob.However,insome cases,itmaynotautoloadthekernelmodulesyouneed. Ifn t s t p e e u orp p e s t p p o e u failed,thenitispossiblethatyournetworkcardwasn'tfoundimmediately.This meansyoumayhavetoloadtheappropriatekernelmodulesmanually. Tofindoutwhatkernelmodulesweprovidefornetworking,usel : s
CodeListing3.1:Searchingforprovidedmodules #llbmdls`nmr/enldiesnt s/i/oue/uae`kre/rvr/e

Ifyoufindadriverforyournetworkcard,usem d r b toloadthekernelmodule: opoe

CodeListing3.2:Usingmodprobetoloadakernelmodule (saxml,wodtepnt2mdl) Aneapeelahce3oue #mdrbce3 opoepnt2

Tocheckifyournetworkcardisnowdetected,usei c n i .Adetectednetworkcardwouldresultinsomething fofg likethis:

CodeListing3.3:Testingavailabilityofyournetworkcard,successful #icnit0 fofgeh ehLnna:tentWdrF:D0:00:0 t0ikecpEhreHadEF:00:00 BODATNAPMLIATT:50erc1 RACSORUTCSMU10Mti: Rakt:ros0dopd0oern:rm: Xpces0err:rpe:vrus0fae0 Takt:ros0dopd0oern:are: Xpces0err:rpe:vrus0crir0 cliin:xuuln0 olsos0tqeee: Rye:00bTye:00b Xbts0(.)Xbts0(.)

Ifhoweveryoureceivethefollowingerror,thenetworkcardisnotdetected:
CodeListing3.4:Testingavailabilityofyournetworkcard,failed #icnit0 fofgeh eh:errfthnnefcnomto:Dvcoon t0roecigitraeifraineientfud

Ifyouhavemultiplenetworkcardsinyoursystemtheyarenamedeth0,eth1,etc.Makesurethatthenetworkcard youwanttouseworkswellandremembertousethecorrectnamingthroughoutthisdocument.Wewillassumethat thenetworkcardeth0isused. Assumingthatyounowhaveadetectednetworkcard,youcanretryn t s t p e e u orp p e s t p p o e u again(which shouldworknow),butforthehardcorepeopleamongstyouweexplainhowtoconfigureyournetworkmanually. Selectoneofthefollowingsectionsbasedonyournetworksetup: UsingDHCPforautomaticIPretrieval PreparingforWirelessAccessifyouhaveawirelesscard UnderstandingNetworkTerminologyexplainswhatyouneedtoknowaboutnetworking Usingifconfigandrouteexplainshowtosetupyournetworkingmanually

UsingDHCP
DHCP(DynamicHostConfigurationProtocol)makesitpossibletoautomaticallyreceivenetworkinginformation(IP address,netmask,broadcastaddress,gateway,nameserversetc.).ThisonlyworksifyouhaveaDHCPserverin yournetwork(orifyourproviderprovidesaDHCPservice).Tohaveanetworkinterfacereceivethisinformation automatically,used c c : hpd
CodeListing3.5:Usingdhcpcd

#dcct0 hpdeh Smewrdisrqietaosh oentokamneurhtyuuete hsnmnoanaepoieyteDCevr otaeaddminmrvddbhHPsre. Ihtcs,ue ntaaes #dccHt0 hpdDeh

Ifthisworks(trypingingsomeinternetserver,likeGoogle),thenyouareallsetandreadytocontinue.Skiptherest ofthissectionandcontinuewithPreparingtheDisks.

PreparingforWirelessAccess
Note:Supportforthei c n i commandisonlyavailableonx86,amd64andppcInstallationCDs.Youcanstillgetthe wofg extensionsworkingotherwisebyfollowingtheinstructionsofthelinuxwlanngproject.

Ifyouareusingawireless(802.11)card,youmayneedtoconfigureyourwirelesssettingsbeforegoinganyfurther. Toseethecurrentwirelesssettingsonyourcard,youcanusei c n i .Runningi c n i mightshow wofg wofg somethinglike:

CodeListing3.6:Showingthecurrentwirelesssettings #icnit0 wofgeh ehIE0.1DESD"etooe t0EE821SSI:GnoNd" Md:aaeFeuny242HAcson:0:95:1C:2 oeMngdrqec:.4GzcesPit00:B1:CF BtRt:1bsToe=0dmSniiiy0655 iae1M/xPwr2Bestvt=/53 Rtylmt1Th:frgettrof erii:6RStrofFamnh:f PwrMngmn:f oeaaeetof Lnult:51Sgaee:5BNielvl0B ikQaiy2/0inllvl1dmosee:12dm Rnaiwd50xivldcyt0Rnairg0T xivldni:91Rnairp:xivldfa:x ecsiertis27Ivldms:522Mseecn8 xesvere:3naiic308isdbao:4 Note:Somewirelesscardsmayhaveadevicenameofw a 0 l n orr 0 a insteadofe h .Runi c n i withoutanycommand t0 wofg lineparameterstodeterminethecorrectdevicename.

Formostusers,thereareonlytwosettingsthatmightbeimportanttochange,theESSID(akawirelessnetwork name)ortheWEPkey.IftheESSIDandAccessPointaddresslistedarealreadythatofyouraccesspointandyou arenotusingWEP,thenyourwirelessisworking.IfyouneedtochangeyourESSID,oraddaWEPkey,youcan issuethefollowingcommands:

Note:IfyourwirelessnetworkissetupwithWPAorWPA2,youwillneedtousew a s p l c n .Formoreinformationon p_upiat configuringwirelessnetworkinginGentooLinux,pleasereadtheWirelessNetworkingchapterintheGentooHandbook. CodeListing3.7:ChangingESSIDand/oraddingWEPkey (hssthewraetGnoNd" Tiestentoknmo"etooe) #icnit0esdGnoNd wofgehsietooe (hssteEe) TiesahxWPky #icnit0ky13131313ac wofgehe24242424bd (hsstnACIkypeitwts" TiesaSIerfxiih":) #icnit0kyssmasod wofgehe:oepswr

Youcanthenconfirmyourwirelesssettingsagainbyusingi c n i .Onceyouhavewirelessworking,youcan wofg continueconfiguringtheIPlevelnetworkingoptionsasdescribedinthenextsection(UnderstandingNetwork Terminology)orusethen t s t p e e u toolasdescribedpreviously.

UnderstandingNetworkTerminology
Note:IfyouknowyourIPaddress,broadcastaddress,netmaskandnameservers,thenyoucanskipthissubsectionandcontinue withUsingifconfigandroute.

Ifalloftheabovefails,youwillhavetoconfigureyournetworkmanually.Thisisnotdifficultatall.However,you needtobefamiliarwithsomenetworkterminology,asyouwillneedittobeabletoconfigureyournetworktoyour

satisfaction.Afterreadingthis,youwillknowwhatagatewayis,whatanetmaskservesfor,howabroadcast addressisformedandwhyyouneednameservers. Inanetwork,hostsareidentifiedbytheirIPaddress(InternetProtocoladdress).Suchanaddressisacombination offournumbersbetween0and255.Well,atleastthatishowweperceiveit.Inreality,suchanIPaddressconsists of32bits(onesandzeros).Let'sviewanexample:

CodeListing3.8:ExampleofanIPaddress Idrsnmes:121802 PAdes(ubr)9.6.. Idrsbt)1000000000000000 PAdes(is:1000111000000001 9180 1262

SuchanIPaddressisuniquetoahostasfarasallaccessiblenetworksareconcerned(i.e.everyhostthatyouare abletoreachmusthaveauniqueIPaddress).Inordertodistinguishbetweenhostsinsideandoutsideanetwork, theIPaddressisdividedintwoparts:thenetworkpartandthehostpart. Theseparationiswrittendownwiththenetmask,acollectionofonesfollowedbyacollectionofzeros.Thepartof theIPthatcanbemappedontheonesisthenetworkpart,theotheroneisthehostpart.Asusual,thenetmask canbewrittendownasanIPaddress.

CodeListing3.9:Exampleofnetwork/hostseparation Idrs:918 Pades12602 1000000000000000 1000111000000001 Ntak1111111111110000 ems:1111111111110000 52525 25550 + ++ Ntokot ewrHs

Inotherwords,192.168.0.14isstillpartofourexamplenetwork,but192.168.1.2isnot. ThebroadcastaddressisanIPaddresswiththesamenetworkpartasyournetwork,butwithonlyonesashost part.EveryhostonyournetworklistenstothisIPaddress.Itistrulymeantforbroadcastingpackets.

CodeListing3.10:Broadcastaddress Idrs:918 Pades12602 1000000000000000 1000111000000001 Bodat1000000000001111 racs:1000111000001111 91825 12605 + ++ ewrot NtokHs

Tobeabletosurfontheinternet,youmustknowwhichhostsharestheInternetconnection.Thishostiscalledthe gateway.Sinceitisaregularhost,ithasaregularIPaddress(forinstance192.168.0.1). WepreviouslystatedthateveryhosthasitsownIPaddress.Tobeabletoreachthishostbyaname(insteadofan IPaddress)youneedaservicethattranslatesaname(suchasdev.gentoo.org)toanIPaddress(suchas 64.5.62.82).Suchaserviceiscalledanameservice.Tousesuchaservice,youmustdefinethenecessaryname serversin/ t / e o v c n . ecrsl.of Insomecases,yourgatewayalsoservesasnameserver.Otherwiseyouwillhavetoenterthenameserversprovided byyourISP. Tosummarise,youwillneedthefollowinginformationbeforecontinuing:
NetworkItem YourIPaddress Netmask Broadcast Gateway Nameserver(s) Example 192.168.0.2 255.255.255.0 192.168.0.255 192.168.0.1 195.130.130.5,195.130.130.133

Usingifconfigandroute
Settingupyournetworkconsistsofthreesteps.FirstweassignourselvesanIPaddressusingi c n i .Thenwe fofg setuproutingtothegatewayusingr u e o t .ThenwefinishupbyplacingthenameserverIPsin /t/eovcn. ecrsl.of ToassignanIPaddress,youwillneedyourIPaddress,broadcastaddressandnetmask.Thenexecutethe followingcommand,substituting$ I _ D R withyourIPaddress,$ B O D A T withyourbroadcastaddress {PAD} {RACS} and$ N T A K withyournetmask: {EMS}
CodeListing3.11:Usingifconfig #icnit0$I_DRracs{RACS}ntak$NTAKp fofgeh{PAD}bodat$BODATems{EMS}u

Nowsetuproutingusingr u e o t .Substitute$ G T W Y withyourgatewayIPaddress: {AEA}

CodeListing3.12:Usingroute #rueaddfutg{AEA} otdealw$GTWY

Nowopen/ t / e o v c n withyourfavoriteeditor(inourexample,weusen n ): ecrsl.of ao

CodeListing3.13:Creating/etc/resolv.conf #nnw/t/eovcn aoecrsl.of

Nowfillinyournameserver(s)usingthefollowingasatemplate.Makesureyousubstitute$ N M S R E 1 and {AEEVR} $ N M S R E 2 withtheappropriatenameserveraddresses: {AEEVR}

CodeListing3.14:/etc/resolv.conftemplate nmsre{AEEVR} aeevr$NMSRE1 nmsre{AEEVR} aeevr$NMSRE2

That'sit.NowtestyournetworkbypingingsomeInternetserver(likeGoogle).Ifthisworks,congratulationsthen. YouarenowreadytoinstallGentoo.ContinuewithPreparingtheDisks.

4.PreparingtheDisks
4.a.IntroductiontoBlockDevices BlockDevices
We'lltakeagoodlookatdiskorientedaspectsofGentooLinuxandLinuxingeneral,includingLinuxfilesystems, partitionsandblockdevices.Then,onceyou'refamiliarwiththeinsandoutsofdisksandfilesystems,you'llbe guidedthroughtheprocessofsettinguppartitionsandfilesystemsforyourGentooLinuxinstallation. Tobegin,we'llintroduceblockdevices.Themostfamousblockdeviceisprobablytheonethatrepresentsthefirst driveinaLinuxsystem,namely/ e / d .SCSIandSerialATAdrivesarebothlabeled/ e / d evenIDE dvsa dvs* drivesarelabeled/ e / d withthenewlibataframeworkinthekernel.Ifyou'reusingtheolddeviceframework, dvs* thenyourfirstIDEdriveis/ e / d . dvha Theblockdevicesaboverepresentanabstractinterfacetothedisk.Userprogramscanusetheseblockdevicesto interactwithyourdiskwithoutworryingaboutwhetheryourdrivesareIDE,SCSIorsomethingelse.Theprogram cansimplyaddressthestorageonthediskasabunchofcontiguous,randomlyaccessible512byteblocks.

Partitions
AlthoughitistheoreticallypossibletouseafulldisktohouseyourLinuxsystem,thisisalmostneverdonein practice.Instead,fulldiskblockdevicesaresplitupinsmaller,moremanageableblockdevices.OnAMD64 systems,thesearecalledpartitions. Partitionsaredividedinthreetypes:primary,extendedandlogical.

AprimarypartitionisapartitionwhichhasitsinformationstoredintheMBR(masterbootrecord).AsanMBRis verysmall(512bytes)onlyfourprimarypartitionscanbedefined(forinstance,/ e / d 1 d v s a to/ e / d 4 d v s a ). Anextendedpartitionisaspecialprimarypartition(meaningtheextendedpartitionmustbeoneofthefourpossible primarypartitions)whichcontainsmorepartitions.Suchapartitiondidn'texistoriginally,butasfourpartitionswere toofew,itwasbroughttolifetoextendtheformattingschemewithoutlosingbackwardcompatibility. Alogicalpartitionisapartitioninsidetheextendedpartition.Theirdefinitionsaren'tplacedinsidetheMBR,butare declaredinsidetheextendedpartition.

AdvancedStorage
TheAMD64InstallationCDsprovidesupportforLVM2.LVM2increasestheflexibilityofferedbyyourpartitioning setup.Duringtheinstallationinstructions,wewillfocuson"regular"partitions,butitisstillgoodtoknowLVM2is supportedaswell.

4.b.DesigningaPartitioningScheme DefaultPartitioningScheme
Ifyouarenotinterestedindrawingupapartitioningschemeforyoursystem,youcanusethepartitioningscheme weusethroughoutthisbook:
Partition
/e/d1 dvsa /e/d2 dvsa /e/d3 dvsa

Filesystem ext2 (swap) ext3

Size 32M 512M Restofthedisk

Description Bootpartition Swappartition Rootpartition

Ifyouareinterestedinknowinghowbigapartitionshouldbe,orevenhowmanypartitionsyouneed,readon. OtherwisecontinuenowwithpartitioningyourdiskbyreadingUsingfdisktoPartitionyourDiskorUsingpartedto PartitionyourDisk(botharepartitioningtools,f i k d s iswellknownandstable,p r e isabitmorerecentbut atd supportspartitionslargerthan2TB).

HowManyandHowBig?
Thenumberofpartitionsishighlydependentonyourenvironment.Forinstance,ifyouhavelotsofusers,youwill mostlikelywanttohaveyour/ o e h m separateasitincreasessecurityandmakesbackupseasier.Ifyouare installingGentootoperformasamailserver,your/ a shouldbeseparateasallmailsarestoredinside/ a .A vr vr goodchoiceoffilesystemwillthenmaximiseyourperformance.Gameserverswillhaveaseparate/ p asmost ot gamingserversareinstalledthere.Thereasonissimilarfor/ o e h m :securityandbackups.Youwilldefinitelywant tokeep/ s big:notonlywillitcontainthemajorityofapplications,thePortagetreealonetakesaround500 ur Mbyteexcludingthevarioussourcesthatarestoredinit. Asyoucansee,itverymuchdependsonwhatyouwanttoachieve.Separatepartitionsorvolumeshavethe followingadvantages: Youcanchoosethebestperformingfilesystemforeachpartitionorvolume Yourentiresystemcannotrunoutoffreespaceifonedefuncttooliscontinuouslywritingfilestoapartition orvolume Ifnecessary,filesystemchecksarereducedintime,asmultiplecheckscanbedoneinparallel(althoughthis advantageismorewithmultipledisksthanitiswithmultiplepartitions) Securitycanbeenhancedbymountingsomepartitionsorvolumesreadonly,nosuid(setuidbitsare ignored),noexec(executablebitsareignored)etc. However,multiplepartitionshavedisadvantagesaswell.Ifnotconfiguredproperly,youwillhaveasystemwithlots offreespaceononepartitionandnoneonanother.Anothernuisanceisthatseparatepartitionsespeciallyfor importantmountpointslike/ s or/ a oftenrequiretheadministratortobootwithaninitramfstomountthe ur vr partitionbeforeotherbootscriptsstart.Thisisn'talwaysthecasethough,soYMMV. Thereisalsoa15partitionlimitforSCSIandSATAunlessyouuseGPTlabels.

Asanexamplepartitioning,weshowyouonefora20GBdisk,usedasademonstrationlaptop(containing webserver,mailserver,gnome,...):
CodeListing2.1:Filesystemusageexample $dh f FlsseTpSzUevis%Mutdo ieytmyeiesdAalUeonen /e/d5et5912312%/ dvsax30M3M5M8 /e/d2et5030186%/oe dvsax3.G.G.G3hm /e/d7et7962138%/s dvsax3.G.G.G3ur /e/d8et0143475%/p dvsax311M8M7M1ot /e/d9et2067133%/a dvsax3.G0M.G2vr /e/d1et1713%/ot dvsax25M1M3M6bo /e/d6sa56254%<oone> dvsawp1M1M0M2ntmutd (nattoepcouueuaeB Upriindsaefrftrsg:2G)

/ s isratherfull(83%used)here,butonceallsoftwareisinstalled,/ s doesn'ttendtogrowthatmuch. ur ur Althoughallocatingafewgigabytesofdiskspacefor/ a mayseemexcessive,rememberthatPortageusesthis vr partitionbydefaultforcompilingpackages.Ifyouwanttokeep/ a atamorereasonablesize,suchas1GB,you vr willneedtoalteryourP R A E T P I variablein/ t / a e c n topointtothepartitionwithenoughfree OTG_MDR ecmk.of spaceforcompilingextremelylargepackagessuchasOpenOffice.

4.c.UsingfdisktoPartitionyourDisk
Important:Ifyourenvironmentwilldealwithpartitionslargerthan2TB,pleaseusetheUsingpartedtoPartitionyourDisk instructionsinstead.f i k d s isnotabletodealwithlargerpartitions.

Thefollowingpartsexplainhowtocreatetheexamplepartitionlayoutusingf i k d s .Theexamplepartitionlayout wasmentionedearlier:

Partition
/e/d1 dvsa /e/d2 dvsa /e/d3 dvsa

Description Bootpartition Swappartition Rootpartition

Changeyourpartitionlayoutaccordingtoyourownpreference.

ViewingtheCurrentPartitionLayout
fik d s isapopularandpowerfultooltosplityourdiskintopartitions.Fireupf i k d s onyourdisk(inourexample, weuse/ e / d ): dvsa
CodeListing3.1:Startingfdisk #fik/e/d dsdvsa

Onceinf i k d s ,you'llbegreetedwithapromptthatlookslikethis:
CodeListing3.2:fdiskprompt Cmad(oep: omnmfrhl)

Typep todisplayyourdisk'scurrentpartitionconfiguration:
CodeListing3.3:Anexamplepartitionconfiguration Cmad(oep:p omnmfrhl) Dsdvsa4ed,6etr,28yidr ik/e/d:20has3scos14clnes Uis=clneso521ye ntyidrf110*52bts eieBoSatEdlcsISse DvcottrnBokdytm /e/d1*140888Lnx dvsa1150+3iu

/e/d2596608Lnxsa dvsa142402iuwp /e/d3005708Lnx dvsa571863iu /e/d41145880Etne dvsa72819145xedd /e/d512915888Lnx dvsa70000+3iu /e/d6203815888Lnx dvsa14000+3iu /e/d7396620688Lnx dvsa42114+3iu /e/d8679420688Lnx dvsa20114+3iu /e/d9951497788Lnx dvsa028666+3iu Cmad(oep: omnmfrhl)

ThisparticulardiskisconfiguredtohousesevenLinuxfilesystems(eachwithacorrespondingpartitionlistedas "Linux")aswellasaswappartition(listedas"Linuxswap").

RemovingallPartitions
Wewillfirstremoveallexistingpartitionsfromthedisk.Typed todeleteapartition.Forinstance,todeletean existing/ e / d 1 dvsa:
CodeListing3.4:Deletingapartition Cmad(oep:d omnmfrhl) Priinnme14:1 attoubr()

Thepartitionhasbeenscheduledfordeletion.Itwillnolongershowupifyoutypep ,butitwillnotbeeraseduntil yourchangeshavebeensaved.Ifyoumadeamistakeandwanttoabortwithoutsavingyourchanges,typeq immediatelyandhitenterandyourpartitionwillnotbedeleted. Now,assumingthatyoudoindeedwanttowipeoutallthepartitionsonyoursystem,repeatedlytypep toprintout apartitionlistingandthentyped andthenumberofthepartitiontodeleteit.Eventually,you'llendupwitha partitiontablewithnothinginit:

CodeListing3.5:Anemptypartitiontable Dsdvsa00G,305240bts ik/e/d:3.B00814ye 20has3scostak86clnes 4ed,6etr/rc,37yidr Uis=clneso521714ye ntyidrf110*52=7440bts DvcottrnBokdytm eieBoSatEdlcsISse Cmad(oep: omnmfrhl)

Nowthattheinmemorypartitiontableisempty,we'rereadytocreatethepartitions.Wewilluseadefault partitioningschemeasdiscussedpreviously.Ofcourse,don'tfollowtheseinstructionstotheletterifyoudon'twant thesamepartitioningscheme!

CreatingtheBootPartition
Wefirstcreateasmallbootpartition.Typen tocreateanewpartition,thenp toselectaprimarypartition,followed by1 toselectthefirstprimarypartition.Whenpromptedforthefirstcylinder,hitenter.Whenpromptedforthelast cylinder,type+ 2 tocreateapartition32Mbyteinsizeandsetitsbootableflag: 3M
CodeListing3.6:Creatingthebootpartition Cmad(oep:n omnmfrhl) Cmadato omncin eetne xedd ppiaypriin() rmratto14 p Priinnme14:1 attoubr() Frtclne137,dfut1:(ine) isyidr(86eal)HtEtr Uigdfutvle1 snealau Lsyidroszr+ier+ie137,dfut37)3M atclner+ieoszMoszK(86eal86:+2

Now,whenyoutypep ,youshouldseethefollowingpartitionprintout:
CodeListing3.7:Createdbootpartition Cmad(oep:p omnmfrhl) Dsdvsa00G,305240bts ik/e/d:3.B00814ye 20has3scostak86clnes 4ed,6etr/rc,37yidr Uis=clneso521714ye ntyidrf110*52=7440bts eieBoSatEdlcsISse DvcottrnBokdytm /e/d1140888Lnx dvsa1150+3iu

Weneedtomakethispartitionbootable.Typea totogglethebootableflagonapartitionandselect1 .Ifyoupress p again,youwillnoticethatan* isplacedinthe"Boot"column.

CreatingtheSwapPartition
Let'snowcreatetheswappartition.Todothis,typen tocreateanewpartition,thenp totellfdiskthatyouwanta primarypartition.Thentype2 tocreatethesecondprimarypartition,/ e / d 2 d v s a inourcase.Whenpromptedfor thefirstcylinder,hitenter.Whenpromptedforthelastcylinder,type+ 1 M 5 2 tocreateapartition512MBinsize. Afteryou'vedonethis,typet tosetthepartitiontype,2 toselectthepartitionyoujustcreatedandthentypein8 2 tosetthepartitiontypeto"LinuxSwap".Aftercompletingthesesteps,typingp shoulddisplayapartitiontablethat lookssimilartothis:
CodeListing3.8:Partitionlistingaftercreatingaswappartition Cmad(oep:p omnmfrhl) Dsdvsa00G,305240bts ik/e/d:3.B00814ye 20has3scostak86clnes 4ed,6etr/rc,37yidr Uis=clneso521714ye ntyidrf110*52=7440bts eieBoSatEdlcsISse DvcottrnBokdytm /e/d1*140888Lnx dvsa1150+3iu /e/d2510508Lnxsa dvsa185622iuwp

CreatingtheRootPartition
Finally,let'screatetherootpartition.Todothis,typen tocreateanewpartition,thenp totellfdiskthatyouwanta primarypartition.Thentype3 tocreatethethirdprimarypartition,/ e / d 3 d v s a inourcase.Whenpromptedforthe firstcylinder,hitenter.Whenpromptedforthelastcylinder,hitentertocreateapartitionthattakesuptherestof theremainingspaceonyourdisk.Aftercompletingthesesteps,typingp shoulddisplayapartitiontablethatlooks similartothis:
CodeListing3.9:Partitionlistingaftercreatingtherootpartition Cmad(oep:p omnmfrhl) Dsdvsa00G,305240bts ik/e/d:3.B00814ye 20has3scostak86clnes 4ed,6etr/rc,37yidr Uis=clneso521714ye ntyidrf110*52=7440bts eieBoSatEdlcsISse DvcottrnBokdytm /e/d1*140888Lnx dvsa1150+3iu /e/d2510508Lnxsa dvsa185622iuwp /e/d328689208Lnx dvsa83726003iu

SavingthePartitionLayout
Tosavethepartitionlayoutandexitf i k d s ,typew .
CodeListing3.10:Saveandexitfdisk

Cmad(oep:w omnmfrhl)

Nowthatyourpartitionsarecreated,youcancontinuewithCreatingFilesystems.

4.d.UsingpartedtoPartitionyourDisk
Inthischapter,weguideyouthroughthecreationoftheexamplepartitionlayoutmentionedearlierinthe instructions.Unlikethepreviouschapter,wedescribethemethodusingthep r e applicationinstead.Both atd p r e andf i k atd d s offerthesamefunctions,soifyoupartitionedyoursystemusingf i k d s already,youcanskip thissectionandcontinuewithCreatingFilesystems. Theexamplepartitionlayoutweuseisshowninthenexttable:
Partition
/e/d1 dvsa /e/d2 dvsa /e/d3 dvsa

Description Bootpartition Swappartition Rootpartition

Changeyourpartitionlayoutaccordingtoyourownpreference.

ViewingtheCurrentPartitionLayout
Thep r e applicationisasomewhatmoremodernvariantoff i k atd d s .Itoffersasimplerinterfaceforpartitioning yourdisksandsupportsverylargepartitions(morethan2TB).Fireupp r e onyourdisk(inourexample,we atd use/ e / d ): dvsa
CodeListing4.1:Startingparted #predvsa atd/e/d GUPre. Natd23 Uig/e/d sndvva WloetNatdye'epoveitoomns ecmoGUPre!Tphl'tiwalsfcmad.

Tofindoutaboutalloptionssupportedbyp r e ,typeh l andpressreturn.Fornow,wejustcontinueby atd ep askingp r e toshowthepartitionscurrentlyinuseontheselecteddisk.Thep i t atd r n commandcanbeusedfor that.

CodeListing4.2:Anexamplepartitionconfigurationshownbyparted (atdrn pre)pit MdlCIBokDvc oe:SSlceie Dsdvsa15B ik/e/d:2.G Scoie(oia/hscl:52/1B etrszlgclpyia)1B52 PriinTbeso attoal:mds NmeSatEdSzTpiesselg ubrtrnieyeFlytmFas 5224M24Mpiayx4 11B18B18Brmret 24M32M17Mpiayiuwpv) 218B22B04Brmrlnxsa(1 32M2.G1.Gpiayv 322B15B83Brmrlm

Optional:SettingtheGPTLabel
Mostdisksonx86/amd64arepreparedusinganmsdoslabel.However,ifyouplanoncreatinghugepartitions(2TB andmore),youmustuseagptlabel(theGUIDPartitionType)foryourdisk.Usingp r e ,thiscanbe atd accomplishedwithm l b l g t kaep:
Warning:Changingthepartitiontypewillremoveallpartitionsfromyourdisk.Alldataonthediskwillbelost. CodeListing4.3:SettingtheGPTlabel (atdkaep pre)mlblgt

RemovingallPartitions
Ifthisisn'tdoneyet(forinstancethroughthem l b l k a e operationearlier,orbecausethediskisafreshlyformatted one),wewillfirstremoveallexistingpartitionsfromthedisk.Typer n m e > m < u b r where<number>isthepartition youwanttoremove.
CodeListing4.4:Removingapartitionfromthedisk (atdm2 pre)r

Dothesameforallotherpartitionsthatyoudon'tneed.However,makesureyoudonotmakeanymistakeshere p r e executesthechangesimmediate(unlikef i k atd d s whichstagesthem,allowingauserto"undo"hischanges beforesavingorexitingf i k d s ).

CreatingthePartitions
Nowlet'screatethepartitionswementionedearlier.Creatingpartitionswithp r e isn'tverydifficultallweneed atd todoisinformp r e aboutthefollowingsettings: atd Thepartitiontypetouse.Thisusuallyisprimaryincaseyouarenotgoingtohavemorethan4partitions (withthemsdospartitionlabel).Otherwise,youwillneedtomakeyourfourthpartitionanextendedone whichhoststherestofthedisk,andcreatelogicalpartitionsinsideit.Ifyouuseagptlabeledpartition,then thereisnolimitonthenumberofprimarypartitions. Thefilesystemtypetouse.Thep r e applicationsupportsmostcommonfilesystemsandknowswhich atd kindofpartitionIDitneedstouseforthesepartitions.Thisdoesnotmeanthatp r e willcreateafile atd systemonthepartition(youcanwiththem p r f command,butwe'llusetheregularm f . commands kats ks* laterforthispurpose).ThepartitionIDisoftenusedbyautodetectiontoolstoknowwhattodowitha particularpartition. Thestartlocationofapartition(whichcanbeexpressedinMBorGB) Theendlocationofthepartition(whichcanbeexpressedinMBorGB) Oneadvantageofp r e isthatyoucaneasilyjustusethepartitionsizestoautomaticallyfindthecorrectstart atd andendlocationasyouwillseeinthenextexample.
CodeListing4.5:Creatingthepartitions #Cet2mye/otpriin raea3btboatto (atdkatpiayet2b pre)mprrmrx203m Wrigheutnattosntpoellgeoetpromne ann:Tersligpriiniorpryaindfrbsefrac. Inr/acl goeCne?i #Cet1btwppriin raea52myesaatto (atdkatpiaylnxsa2b52b pre)mprrmriuwp3m4m #Cetattohtsastermiigds. raeapriintapnheannik #s(iun)masteedohik 1mnsoesenhnfteds (atdkatpiayet4m1 pre)mprrmrx452bs Wrigoeuseattorm52Bt15B ann:Yurqetdapriinfo4Mo2.G. Tecoetlctoecnmngs52Bt15B hlssoainwaaaei4Mo2.G. Ihssilacpaloyu stitlcetbeto? YsN?y e/o

Youcannowp i t r n thepartitionlayoutagaintovalidateifeverythingisasexpected.Whenyouaresatisfied,use theq i commandtoexitp r e . ut atd

4.e.CreatingFilesystems Introduction
Nowthatyourpartitionsarecreated,itistimetoplaceafilesystemonthem.Ifyoudon'tcareaboutwhatfilesystem tochooseandarehappywithwhatweuseasdefaultinthishandbook,continuewithApplyingaFilesystemtoa Partition.Otherwisereadontolearnabouttheavailablefilesystems...

Filesystems
Severalfilesystemsareavailable.Someofthemarefoundstableontheamd64architecture,othersaren't.The followingfilesystemsarefoundtobestable:ext2,ext3,ext4andXFS.JFSandReiserFSmayworkbutneedmore testing.Ifyou'rereallyadventurousyoucantrytheotherfilesystems. ext2isthetriedandtrueLinuxfilesystembutdoesn'thavemetadatajournaling,whichmeansthatroutineext2 filesystemchecksatstartuptimecanbequitetimeconsuming.Thereisnowquiteaselectionofnewergeneration journaledfilesystemsthatcanbecheckedforconsistencyveryquicklyandarethusgenerallypreferredovertheir nonjournaledcounterparts.Journaledfilesystemspreventlongdelayswhenyoubootyoursystemandyour filesystemhappenstobeinaninconsistentstate.IfyouintendtoinstallGentooonaverysmalldisk(lessthan 4GB),thenyou'llneedtotellext2toreserveenoughinodeswhenyoucreatethefilesystem.Them e f k2s applicationusesthe"bytesperinode"settingtocalculatehowmanyinodesafilesystemshouldhave.Byrunning mefTsal/e/dvc> k 2 s m l d v < e i e thenumberofinodeswillgenerallyquadrupleforagivenfilesystemasits "bytesperinode"reducesfromoneevery16kBtooneevery4kB.Youcantunethisevenfurtherbyusingm e f k2s rtodv<eie. i<ai>/e/dvc> ext3isthejournaledversionoftheext2filesystem,providingmetadatajournalingforfastrecoveryinadditionto otherenhancedjournalingmodeslikefulldataandordereddatajournaling.ItusesanHTreeindexthatenables highperformanceinalmostallsituations.Inshort,ext3isaverygoodandreliablefilesystem.Ext3isthe recommendedallpurposeallplatformfilesystem.IfyouintendtoinstallGentooonaverysmalldisk(lessthan 4GB),thenyou'llneedtotellext3toreserveenoughinodeswhenyoucreatethefilesystem.Them e f k2s applicationusesthe"bytesperinode"settingtocalculatehowmanyinodesafilesystemshouldhave.Byrunning m e f j m l d v < e i e thenumberofinodeswillgenerallyquadrupleforagivenfilesystem k2sTsal/e/dvc> asits"bytesperinode"reducesfromoneevery16kBtooneevery4kB.Youcantunethisevenfurtherbyusing mefjrtodv<eie. k2si<ai>/e/dvc> ext4isafilesystemcreatedasaforkofext3bringingnewfeatures,performanceimprovementsandremovalofsize limitswithmoderatechangestotheondiskformat.Itcanspanvolumesupto1EBandwithmaximumfilesizeof 16TB.Insteadoftheclassicext2/3bitmapblockallocationext4usesextents,whichimprovelargefileperformance andreducefragmentation.Ext4alsoprovidesmoresophisticatedblockallocationalgorithms(delayedallocationand multiblockallocation)givingthefilesystemdrivermorewaystooptimisethelayoutofdataonthedisk.Theext4 filesystemisacompromisebetweenproductiongradecodestabilityandthedesiretointroduceextensionstoan almostdecadeoldfilesystem. JFSisIBM'shighperformancejournalingfilesystem.JFSisalight,fastandreliableB+treebasedfilesystemwith goodperformanceinvariousconditions. ReiserFSisaB+treebasedjournaledfilesystemthathasgoodoverallperformance,especiallywhendealingwith manytinyfilesatthecostofmoreCPUcycles.ReiserFSappearstobelessmaintainedthanotherfilesystems. XFSisafilesystemwithmetadatajournalingwhichcomeswitharobustfeaturesetandisoptimizedforscalability. XFSseemstobelessforgivingtovarioushardwareproblems.

ApplyingaFilesystemtoaPartition
Tocreateafilesystemonapartitionorvolume,therearetoolsavailableforeachpossiblefilesystem:
Filesystem ext2 ext3 ext4 reiserfs xfs jfs CreationCommand
mf.x2 kset mf.x3 kset mf.x4 kset mrief kesrs mf.f ksxs mf.f ksjs

Forinstance,tohavethebootpartition(/ e / d 1 d v s a inourexample)inext2andtherootpartition(/ e / d 3 d v s a in ourexample)inext3(asinourexample),youwoulduse:

CodeListing5.1:Applyingafilesystemonapartition

#mf.x2/e/d1 ksetdvsa #mf.x3/e/d3 ksetdvsa

Nowcreatethefilesystemsonyournewlycreatedpartitions(orlogicalvolumes).

ActivatingtheSwapPartition
m s a isthecommandthatisusedtoinitializeswappartitions: kwp
CodeListing5.2:CreatingaSwapsignature #msadvsa kwp/e/d2

Toactivatetheswappartition,uses a o : wpn
CodeListing5.3:Activatingtheswappartition #saodvsa wpn/e/d2

Createandactivatetheswapwiththecommandsmentionedabove.

4.f.Mounting
Nowthatyourpartitionsareinitializedandarehousingafilesystem,itistimetomountthosepartitions.Usethe mut o n command.Don'tforgettocreatethenecessarymountdirectoriesforeverypartitionyoucreated.Asan examplewemounttherootandbootpartition:
CodeListing6.1:Mountingpartitions #mut/e/d3/n/eto ondvsamtgno #mdr/n/etobo kimtgno/ot #mut/e/d1/n/etobo ondvsamtgno/ot Note:Ifyouwantyour/ m toresideonaseparatepartition,besuretochangeitspermissionsaftermounting:c m d 1 7 tp ho77 /n/etotp m t g n o / m .Thisalsoholdsfor/ a / m . vrtp

Wewillalsohavetomounttheprocfilesystem(avirtualinterfacewiththekernel)on/ r c p o .Butfirstwewillneed toplaceourfilesonthepartitions. ContinuewithInstallingtheGentooInstallationFiles.

5.InstallingtheGentooInstallationFiles
5.a.InstallingaStageTarball SettingtheDate/TimeRight
Beforeyoucontinueyouneedtocheckyourdate/timeandupdateit.Amisconfiguredclockmayleadtostrange resultsinthefuture! Toverifythecurrentdate/time,rund t : ae
CodeListing1.1:Verifyingthedate/time #dt ae FiMr262:8UC20 ra91:11T05

Ifthedate/timedisplayediswrong,updateitusingthed t M D h m Y Y a e M D h m Y Y syntax(Month,Day,hour,minute andYear).Atthisstage,youshoulduseUTCtime.Youwillbeabletodefineyourtimezonelateron.Forinstance, tosetthedatetoMarch29th,16:21intheyear2005:

CodeListing1.2:SettingtheUTCdate/time #dt396105 ae021220

MakingyourChoice
Thenextstepyouneedtoperformistoinstallthestage3tarballontoyoursystem.Youhavetheoptionof downloadingtherequiredtarballfromtheInternetor,ifyoubootedoneoftheGentooUniversalCDs,copyitover fromthediscitself.Inmostcases,thecommandu a e canbeusedtohelpyoudecidewhichstagefileto nmm download. MinimalCDsandLiveDVDsdonotcontainanystage3archive.

5.b.Default:UsingaStagefromtheInternet DownloadingtheStageTarball
GototheGentoomountpointatwhichyoumountedyourfilesystems(mostlikely/ n / e t o m t g n o ):
CodeListing2.1:GoingtotheGentoomountpoint #cmtgno d/n/eto

Dependingonyourinstallationmedium,youhaveacoupleoftoolsavailabletodownloadastage.Ifyouhave lns i k available,thenyoucanimmediatelysurftotheGentoomirrorlistandchooseamirrorclosetoyou:type lnsht:/w.etoogmi/nmrosxl i k t p / w w g n o . r / a n e / i r r . m andpressenter. Ifyoudon'thavel n s i k availableyoushouldhavel n atyourdisposal.Ifyouneedtogothroughaproxy,export yx theh t _ r x andf p p o y tppoy t _ r x variables:
CodeListing2.2:Settingproxyinformationforlynx #eprtppoy"tp/poysre.o:ot xotht_rx=ht:/rx.evrcmpr" #eprt_rx=ht:/rx.evrcmpr" xotfppoy"tp/poysre.o:ot

Wewillnowassumethatyouhavel n s i k atyourdisposal. Selectamirrorcloseby.UsuallyHTTPmirrorssuffice,butotherprotocolsareavailableaswell.Movetothe r l a e / m 6 / u o u l s directory.Thereyoushouldseeallavailablestagefilesforyourarchitecture eessad4atbid/ (theymightbestoredwithinsubdirectoriesnamedaftertheindividualsubarchitectures).SelectoneandpressD to download.Whenyou'refinished,pressQ toquitthebrowser.

CodeListing2.3:Surfingtothemirrorlistingwithlinks #lnsht:/w.etoogmi/nmrosxl iktp/wwgno.r/ane/irr.m (fyunerxuprihlns) Ioedpoyspotwtik: #lnstppoypoysre.o:00ht:/w.etoogmi/nmrosxl ikhtrxrx.evrcm88tp/wwgno.r/ane/irr.m

Makesureyoudownloadastage3tarballinstallationsusingastage1orstage2tarballarenotsupportedanymore. Ifyouwanttochecktheintegrityofthedownloadedstagetarball,usem 5 u andcomparetheoutputwiththe dsm MD5checksumprovidedonthemirror.

CodeListing2.4:Checkingintegrityofastagetarball #m5ucsaem6rlae.a.z.IET dsmtg3ad4<ees>trb2DGSS saem6rlae.a.z:O tg3ad4<ees>trb2K

UnpackingtheStageTarball
Nowunpackyourdownloadedstageontoyoursystem.Weuset r a toproceedasitistheeasiestmethod:
CodeListing2.5:Unpackingthestage #trxjfsae.a.z avptg3*trb2

Makesurethatyouusethesameoptions(x j f v p ).Thex standsforExtract,thev forVerbosetoseewhat

happensduringtheextractionprocess(optional),thej forDecompresswithbzip2,thep forPreservepermissions andthef todenotethatwewanttoextractafile,notstandardinput. Nowthatthestageisinstalled,continuewithInstallingPortage.

5.c.InstallingPortage UnpackingaPortageSnapshot
YounowhavetoinstallaPortagesnapshot,acollectionoffilesthatinformPortagewhatsoftwaretitlesyoucan install,whichprofilesareavailable,etc.

DownloadandInstallaPortageSnapshot
Gotothemountpointwhereyoumountedyourfilesystem(mostlikely/ n / e t o m t g n o ):
CodeListing3.1:GoingtotheGentoomountpoint #cmtgno d/n/eto

Fireupl n s i k (orl n )andgotoourGentoomirrorlist.Pickamirrorclosetoyouandopenthes a s o s yx npht/ directory.There,downloadthelatestPortagesnapshot(p r a e l t s . a . z )byselectingitandpressing otgaettrb2 D .

CodeListing3.2:BrowsingtheGentoomirrorlist #lnsht:/w.etoogmi/nmrosxl iktp/wwgno.r/ane/irr.m

NowexityourbrowserbypressingQ .YouwillnowhaveaPortagesnapshotstoredin/ n / e t o mtgno. Ifyouwanttochecktheintegrityofthedownloadedsnapshot,usem 5 u andcomparetheoutputwiththeMD5 dsm checksumprovidedonthemirror.

CodeListing3.3:CheckingintegrityofaPortagesnapshot #m5ucpraelts.a.z.dsm dsmotgaettrb2m5u praelts.a.z:O otgaettrb2K

Inthenextstep,weextractthePortagesnapshotontoyourfilesystem.Makesurethatyouusetheexactcommand thelastoptionisacapitalC ,notc .

CodeListing3.4:ExtractingthePortagesnapshot #trxjmtgno/otgaettrb2mtgno/s avf/n/etopraelts.a.zC/n/etour

5.d.ConfiguringtheCompileOptions Introduction
TooptimizeGentoo,youcansetacoupleofvariableswhichimpactPortagebehaviour.Allthosevariablescanbe setasenvironmentvariables(usinge p r )butthatisn'tpermanent.Tokeepyoursettings,Portageprovidesyou xot with/ t / a e c n ,aconfigurationfileforPortage.Itisthisfilewewilleditnow. ecmk.of
Note:Acommentedlistingofallpossiblevariablescanbefoundin / n / e t o u r s a e p r a e c n i / a e c n . x m l .ForasuccessfulGentooinstallationyou'llonlyneed mtgno/s/hr/otg/ofgmk.ofeape tosetthevariableswhicharementionedbeneath.

Fireupyourfavoriteeditor(inthisguideweusen n )sowecanaltertheoptimizationvariableswewilldiscuss ao hereafter.

CodeListing4.1:Opening/etc/make.conf #nnw/n/etoecmk.of aomtgno/t/aecn

Asyouprobablynoticed,them k . o f e a p e a e c n . x m l fileisstructuredinagenericway:commentedlinesstartwith "#",otherlinesdefinevariablesusingtheV R A L = c n e t syntax.Them k . o f AIBE"otn" a e c n fileusesthesame syntax.Severalofthosevariablesarediscussednext.

CFLAGSandCXXFLAGS
TheC L G andC X L G variablesdefinetheoptimizationflagsfortheg c FAS XFAS c CandC++compilerrespectively. Althoughwedefinethosegenerallyhere,youwillonlyhavemaximumperformanceifyouoptimizetheseflagsfor eachprogramseparately.Thereasonforthisisbecauseeveryprogramisdifferent. Inm k . o f a e c n youshoulddefinetheoptimizationflagsyouthinkwillmakeyoursystemthemostresponsive generally.Don'tplaceexperimentalsettingsinthisvariabletoomuchoptimizationcanmakeprogramsbehavebad (crash,orevenworse,malfunction). Wewillnotexplainallpossibleoptimizationoptions.Ifyouwanttoknowthemall,readtheGNUOnlineManual(s) ortheg c c infopage(i f c onlyworksonaworkingLinuxsystem).Them k . o f e a p e nogc a e c n . x m l fileitself alsocontainslotsofexamplesandinformationdon'tforgettoreadittoo. Afirstsettingisthe a c = m r h or t n = m u e flag,whichspecifiesthenameofthetargetarchitecture.Possible optionsaredescribedinthem k . o f e a p e a e c n . x m l file(ascomments). Asecondoneisthe flag(thatisacapitalO,notazero),whichspecifiestheg c O c optimizationclassflag. Possibleclassesares (forsizeoptimized),0 (zerofornooptimizations),1 oreven3 ,2 formorespeed optimizationflags(everyclasshasthesameflagsastheonebefore,plussomeextras). 2 O istherecommended default. 3 O isknowntocauseproblemswhenusedsystemwide,sowerecommendthatyoustickto 2 O. Anotherpopularoptimizationflagis i e p p (usepipesratherthantemporaryfilesforcommunicationbetweenthe variousstagesofcompilation).Ithasnoimpactonthegeneratedcode,butusesmorememory.Onsystemswith lowmemory,gccmightgetkilled.Inthatcase,donotusethisflag. Using o i r m o n e (whichdoesn'tkeeptheframepointerinaregisterforfunctionsthatdon'tneed fmtfaepitr one)mighthaveseriousrepercussionsonthedebuggingofapplications. WhenyoudefinetheC L G andC X L G ,youshouldcombineseveraloptimizationflags.Thedefaultvalues FAS XFAS containedinthestage3archiveyouunpackedshouldbegoodenough.Thefollowingexampleisjustanexample:
CodeListing4.2:DefiningtheCFLAGSandCXXFLAGSvariable CLG=ac=82ieneM4srhudueac=oe FAS"mrhkOpp"#ItlE6Tuessolsmrhcr2 #Uetesmetnsfrbtaibe shaestigoohvrals CXLG=$CLG} XFAS"{FAS" Note:YoumayalsowanttoviewtheCompilationOptimizationGuideformoreinformationonhowthevariouscompilationoptions canaffectyoursystem.

MAKEOPTS
WithM K O T youdefinehowmanyparallelcompilationsshouldoccurwhenyouinstallapackage.Agoodchoice AEPS isthenumberofCPUs(orCPUcores)inyoursystemplusone,butthisguidelineisn'talwaysperfect.
CodeListing4.3:MAKEOPTSforaregular,1CPUsystem MKOT=2 AEPS"j"

Ready,Set,Go!
Updateyour/ n / e t o e c m k . o f m t g n o / t / a e c n toyourownpreferenceandsave(n n userswouldhitC r ). ao tlX YouarenowreadytocontinuewithInstallingtheGentooBaseSystem.

6.InstallingtheGentooBaseSystem
6.a.Chrooting

Optional:SelectingMirrors
Inordertodownloadsourcecodequicklyitisrecommendedtoselectafastmirror.Portagewilllookinyour mk.of a e c n filefortheGENTOO_MIRRORSvariableandusethemirrorslistedtherein.Youcansurftoourmirror listandsearchforamirror(ormirrors)closetoyou(asthosearemostfrequentlythefastestones),butweprovidea nicetoolcalledm r o s l c whichprovidesyouwithaniceinterfacetoselectthemirrorsyouwant.Just irreet navigatetothemirrorsofchoiceandpressspacebartoselectoneormoremirrors.
CodeListing1.1:UsingmirrorselectfortheGENTOO_MIRRORSvariable #mroslci>/n/etoecmk.of irreeto>mtgno/t/aecn

AsecondimportantsettingistheSYNCsettinginm k . o f a e c n .Thisvariablecontainsthersyncserveryouwantto usewhenupdatingyourPortagetree(thecollectionofebuilds,scriptscontainingalltheinformationPortageneeds todownloadandinstallsoftware).AlthoughyoucanmanuallyenteraSYNCserverforyourself,m r o s l c irreet caneasethatoperationforyou:

CodeListing1.2:Selectinganrsyncmirrorusingmirrorselect #mroslcio>mtgno/t/aecn irreetr>/n/etoecmk.of

Afterrunningm r o s l c itisadviseabletodoublecheckthesettingsin/ n / e t o e c m k . o f irreet m t g n o / t / a e c n !

Note:IfyouwanttomanuallysetaSYNCserverinm k . o f a e c n ,youshouldcheckoutthecommunitymirrorslistforthemirrors closesttoyou.Werecommendchoosingarotation,suchasr y c u . e t o o g s n . s g n o . r ,ratherthanchoosingasinglemirror.This helpsspreadouttheloadandprovidesafailsafeincaseaspecificmirrorisoffline.

CopyDNSInfo
OnethingstillremainstobedonebeforeweenterthenewenvironmentandthatiscopyingovertheDNS informationin/ t / e o v c n .Youneedtodothistoensurethatnetworkingstillworksevenafterentering ecrsl.of thenewenvironment./ t / e o v c n containsthenameserversforyournetwork. ecrsl.of
CodeListing1.3:CopyoverDNSinformation (h"otosneeomkuewo'oyasmoiik Te"Lpinieddtaesredntcpyblcln) #cL/t/eovcnmtgno/t/ pecrsl.of/n/etoec

MountingthenecessaryFilesystems
Inafewmoments,wewillchangetheLinuxroottowardsthenewlocation.Tomakesurethatthenewenvironment worksproperly,weneedtomakecertainfilesystemsavailablethereaswell. Mountthe/ r c p o filesystemon/ n / e t o p o toallowtheinstallationtousethekernelprovided mtgno/rc informationwithinthechrootedenvironment,andthenmountbindthe/ e and/ y filesystems. dv ss
CodeListing1.4:Mounting/procand/dev #mutrcnnmtgno/rc ontpooe/n/etopo #mutrid/ymtgno/y onbnss/n/etoss #mutrid/emtgno/e onbndv/n/etodv

EnteringthenewEnvironment
Nowthatallpartitionsareinitializedandthebaseenvironmentinstalled,itistimetoenterournewinstallation environmentbychrootingintoit.Thismeansthatwechangefromthecurrentinstallationenvironment(Installation CDorotherinstallationmedium)toyourinstallationsystem(namelytheinitializedpartitions). Thischrootingisdoneinthreesteps.Firstwewillchangetherootfrom/ (ontheinstallationmedium)to /n/eto m t g n o (onyourpartitions)usingc r o .Thenwewillcreateanewenvironmentusinge v u d t , hot npae whichessentiallycreatesenvironmentvariables.Finally,weloadthosevariablesintomemoryusings u c . ore
CodeListing3.7:Chrootingintothenewenvironment

#cromtgnobnbs hot/n/eto/i/ah #evudt npae >eeeaig/t/ds.ah.. >Rgnrtnecl.occe. #sucecpoie ore/t/rfl #eprS=(hotP1 xotP1"cro)$S"

Congratulations!YouarenowinsideyourownGentooLinuxenvironment.Ofcourseitisfarfromfinished,whichis whytheinstallationstillhassomesectionsleft:) Ifyouatanytimewouldneedanotherterminalorconsoletoaccessthechrootenvironment,allyouneedtodoisto executetheabovestepsagain.

6.b.ConfiguringPortage UpdatingthePortagetree
YoushouldnowupdateyourPortagetreetothelatestversion.e e g y c m r e s n doesthisforyou.
CodeListing2.1:UpdatingthePortagetree #eegyc mresn (fyursnlwtriaiesmrmbfesoeil Io'euigasoemnllkoefaeufrrasra cnoeoadhuepintpeptircs: osl,yucnadteqitotooseduhspoes) #eegycqit mresnue

Ifyouarebehindafirewallthatblocksrsynctraffic,youcanusee e g e r y c m r e w b s n whichwilldownloadand installaportagesnapshotforyou. IfyouarewarnedthatanewPortageversionisavailableandthatyoushouldupdatePortage,youshoulddoitnow usinge e g n s o o t g . mreoehtprae

ChoosingtheRightProfile
First,asmalldefinitionisinplace. AprofileisabuildingblockforanyGentoosystem.NotonlydoesitspecifydefaultvaluesforUSE,CFLAGSand otherimportantvariables,italsolocksthesystemtoacertainrangeofpackageversions.Thisisallmaintainedby theGentoodevelopers. Previously,suchaprofilewasuntouchedbytheusers.However,theremaybecertainsituationsinwhichyoumay decideaprofilechangeisnecessary. Youcanseewhatprofileyouarecurrentlyusingwiththefollowingcommand:
CodeListing2.2:Verifyingsystemprofile #eeetpoiels slcrflit Aalbepoiesmiktres vialrflylnagt: []dfutlnxad41. 1eal/iu/m6/00* []dfutlnxad41./eko 2eal/iu/m6/00dstp []dfutlnxad41./evr 3eal/iu/m6/00sre

Asyoucansee,therearealsod s t p e k o ands r e subprofilesavailableforsomearchitectures.Running evr e e e t p o i e l s willshowallavailableprofiles. slcrflit Afterviewingtheavailableprofilesforyourarchitecture,youcanuseadifferentoneifyouwish:

CodeListing2.3:Changingprofiles #eeetpoiest2 slcrfle

Ifyouwanttohaveapure64bitenvironment,withno32bitapplicationsorlibraries,youshoulduseanonmultilib profile:

CodeListing2.4:Switchingtoanonmultilibprofile #eeetpoiels slcrflit Aalbepoiesmiktres vialrflylnagt: []dfutlnxad41. 1eal/iu/m6/00* []dfutlnxad41./eko 2eal/iu/m6/00dstp []dfutlnxad41./omlii 3eal/iu/m6/00nutlb []dfutlnxad41./evr 4eal/iu/m6/00sre (hoetenutlbpoie Coshomliirfl) #eeetpoiest3 slcrfle (eiytecag) Vrfhhne #eeetpoiels slcrflit Aalbepoiesmiktres vialrflylnagt: []dfutlnxad41. 1eal/iu/m6/00 []dfutlnxad41./eko 2eal/iu/m6/00dstp []dfutlnxad41./omlii 3eal/iu/m6/00nutlb* []dfutlnxad41./evr 4eal/iu/m6/00sre Note:Thed v l p r e e o e subprofileisspecificallyforGentooLinuxdevelopmenttasks.Itisnotmeanttohelpsetupgeneral developmentenvironments.

ConfiguringtheUSEvariable
UE S isoneofthemostpowerfulvariablesGentooprovidestoitsusers.Severalprogramscanbecompiledwithor withoutoptionalsupportforcertainitems.Forinstance,someprogramscanbecompiledwithgtksupport,orwith qtsupport.OtherscanbecompiledwithorwithoutSSLsupport.Someprogramscanevenbecompiledwith framebuffersupport(svgalib)insteadofX11support(Xserver). Mostdistributionscompiletheirpackageswithsupportforasmuchaspossible,increasingthesizeoftheprograms andstartuptime,nottomentionanenormousamountofdependencies.WithGentooyoucandefinewhatoptionsa packageshouldbecompiledwith.ThisiswhereU E S comesintoplay. IntheU E S variableyoudefinekeywordswhicharemappedontocompileoptions.Forinstance,sslwillcompilessl supportintheprogramsthatsupportit.XwillremoveXserversupport(notetheminussigninfront).gnomegtk kdeqt4willcompileyourprogramswithgnome(andgtk)support,andnotwithkde(andqt)support,makingyour systemfullytweakedforGNOME. ThedefaultU E S settingsareplacedinthem k . e a l s a e d f u t filesofyourprofile.Youwillfindm k . e a l s aedfut filesinthedirectorywhich/ t / a e p o i e e c m k . r f l pointstoandallparentdirectoriesaswell.ThedefaultU E S settingisthesumofallU E S settingsinallm k . e a l s a e d f u t files.Whatyouplacein/ t / a e c n is ecmk.of calculatedagainstthesedefaultssettings.IfyouaddsomethingtotheU E S setting,itisaddedtothedefaultlist.If youremovesomethingfromtheU E S setting(byplacingaminussigninfrontofit)itisremovedfromthedefaultlist (ifitwasinthedefaultlistatall).Neveralteranythinginsidethe/ t / a e p o i e e c m k . r f l directoryitgets overwrittenwhenyouupdatePortage! AfulldescriptiononU E S canbefoundinthesecondpartoftheGentooHandbook,USEflags.Afulldescriptionon theavailableUSEflagscanbefoundonyoursystemin/ s / o t g / r f l s u e d s . urpraepoie/s.ec
CodeListing2.5:ViewingavailableUSEflags #lsurpraepoie/s.ec es/s/otg/rflsueds (oacoluigyuroesxtbrsig'' Yucnsrlsnorarwky,eiypesnq)

AsanexampleweshowaU E S settingforaKDEbasedsystemwithDVD,ALSAandCDRecordingsupport:
CodeListing2.6:Opening/etc/make.conf #nnw/t/aecn aoecmk.of CodeListing2.7:USEsetting UE"gknmtdvlacr S=tgoeq4keddasd"

7.ConfiguringtheKernel

7.a.Timezone
Youfirstneedtoselectyourtimezonesothatyoursystemknowswhereitislocated.Lookforyourtimezonein /s/hr/oeno u r s a e z n i f ,thencopyitto/ t / o a t m .Pleaseavoidthe eclclie / s / h r / o e n o E c G T timezonesastheirnamesdonotindicatetheexpectedzones.Forinstance, ursaeznif/t/M* GT8 M isinfactGMT+8.
CodeListing1.1:Settingthetimezoneinformation #lursaeznif s/s/hr/oeno (upsoattsuoeBusl) SpoeyuwnoueErp/rses #cursaeznif/uoeBusleclclie p/s/hr/oenoErp/rses/t/oatm (etsttetmzn) Nxehieoe #ehErp/rsesectmzn co"uoeBusl">/t/ieoe

7.c.InstallingtheSources ChoosingaKernel
ThecorearoundwhichalldistributionsarebuiltistheLinuxkernel.Itisthelayerbetweentheuserprogramsand yoursystemhardware.Gentooprovidesitsusersseveralpossiblekernelsources.Afulllistingwithdescriptionis availableattheGentooKernelGuide. ForAMD64basedsystemswehaveg n o o r e (kernelsourcepatchedforextrafeatures). etosucs Chooseyourkernelsourceandinstallitusinge e g . mre
CodeListing2.1:Installingakernelsource #eegetosucs mregnoore

Whenyoutakealookin/ s / r youshouldseeasymlinkcalledl n x ursc i u pointingtoyourkernelsource.Inthis case,theinstalledkernelsourcepointstog n o o r e . . 4 r .Yourversionmaybedifferent,sokeep etosucs2631 thisinmind.

CodeListing2.2:Viewingthekernelsourcesymlink #ll/s/r/iu sursclnx lwrxw1root2Ot110ursclnxiu..4r rxwrxotro1c31:4/s/r/iu>lnx2631

Nowitistimetoconfigureandcompileyourkernelsource.Youcanuseg n e n l e k r e forthis,whichwillbuilda generickernelasusedbytheInstallationCD.Weexplainthe"manual"configurationfirstthough,asitisthebest waytooptimizeyourenvironment. Ifyouwanttomanuallyconfigureyourkernel,continuenowwithDefault:ManualConfiguration.Ifyouwanttouse gnenl e k r e youshouldreadAlternative:Usinggenkernelinstead.

7.c.Default:ManualConfiguration Introduction
ManuallyconfiguringakernelisoftenseenasthemostdifficultprocedureaLinuxusereverhastoperform.Nothing islesstrueafterconfiguringacoupleofkernelsyoudon'tevenrememberthatitwasdifficult) However,onethingistrue:youmustknowyoursystemwhenyoustartconfiguringakernelmanually.Most informationcanbegatheredbyemergingpciutils(e e g c u i s m r e p i t l )whichcontainsl p i s c .Youwillnowbe abletousel p i s c withinthechrootedenvironment.Youmaysafelyignoreanypcilibwarnings(likepcilib:cannot open/sys/bus/pci/devices)thatl p i s c throwsout.Alternatively,youcanrunl p i s c fromanonchrooted environment.Theresultsarethesame.Youcanalsorunl m d s o toseewhatkernelmodulestheInstallationCD uses(itmightprovideyouwithanicehintonwhattoenable). Nowgotoyourkernelsourcedirectoryandexecutem k e u o f g a e m n c n i .Thiswillfireupanncursesbased

configurationmenu.
CodeListing3.1:Invokingmenuconfig #cursclnx d/s/r/iu #mkeuofg aemncni

Youwillbegreetedwithseveralconfigurationsections.We'llfirstlistsomeoptionsyoumustactivate(otherwise Gentoowillnotfunction,ornotfunctionproperlywithoutadditionaltweaks).

ActivatingRequiredOptions
Makesurethateverydriverthatisvitaltothebootingofyoursystem(suchasSCSIcontroller,...)iscompiledinthe kernelandnotasamodule,otherwiseyoursystemwillnotbeabletobootcompletely. Weshallthenselecttheexactprocessortype.Thex86_64kernelmaintainerstronglyrecommendsusersenable MCEfeaturessothattheyareabletobenotifiedofanyhardwareproblems.Onx86_64,theseerrorsarenot printedtod e g m s likeonotherarchitectures,butto/ e / c l g d v m e o .Thisrequiresthea p a m n m e o pdi/clg package.MakesureyouselectIA32Emulationifyouwanttobeabletorun32bitprograms.Gentoowillinstalla multilibsystem(mixed32bit/64bitcomputing)bydefault,sothisoptionisrequired.
Note:Ifyouplantouseanonmultilibprofile(forapure64bitsystem),thenyoudon'thavetoselectIA32Emulationsupport. However,you'llalsoneedtofollowtheinstructionsforswitchingtoanonmultilibprofile,aswellaschoosingthecorrect bootloader. CodeListing3.2:Selectingprocessortypeandfeatures Poesrtpnetrs> rcsoyeadfaue ahnhcvretneotn []McieCek/oehaigrprig neCetrs []ItlMEFaue MCetrs []ADMEFaue PoesrfmlADOtrnAho6)> rcsoaiy(Mpeo/tln4 ()OtrnAho6/amrK peo/tln4Hme/8 ()ItlPleebrtbsdXo ne4/odrNtusaeen ()Cr/eeen oe2nwrXo ()ItlAo netm ()Gnrcx66 eei84 Eeualiefras/Euain xctbeflomtmltos> *A2Euain []I3mlto

NextselectMaintainadevtmpfsfilesystemtomountat/devsothatcriticaldevicefilesarealreadyavailableearly inthebootprocess.
CodeListing3.3:Enablingdevtmpfssupport Dvcrvr> eieDies GnrcDiepin> eeirvrOtos []Mitietpsflsseomutadv *ananadvmfieytmtont/e []Atmutdvmft/e,atrtekreonehots uoonetpsadvfehenlmutdterof

NowgotoF l y t m andselectsupportforthefilesystemsyouuse.Don'tcompilethemasmodules, ieSses otherwiseyourGentoosystemwillnotbeabletomountyourpartitions.AlsoselectV r u l m m r and/ r c itaeoy po flytm iesse.

CodeListing3.4:Selectingnecessaryfilesystems Flytm> iesses (eetoeooeoholwnpinsneeyyuytm Slcnrmrftefloigotosaeddborsse) <>Scnxeddfupr *eodetnesspot <>Etoralniesseupr *x3junligflytmspot <>TeEtneet)flsse *hxedd4(x4ieytm <>Riefupr *esrsspot <>JSflsseupr *Fieytmspot <>XSflsseupr *Fieytmspot .. .

Pedieytm> suoFlsses []/rcflytmspot *poiesseupr []Vrulmmriesseuprfrehs *itaeoyflytmspot(omrsmf) (nbeGTpriinlblspotiosdtarvosy EalPattoaeuprfyuuehtpeiul) PriinTps attoye> []Avneattoeeto *dacdpriinslcin .. . []EIGIattoupr *FUDPriinspot

IfyouareusingPPPoEtoconnecttotheInternetoryouareusingadialupmodem,youwillneedthefollowing optionsinthekernel:
CodeListing3.5:SelectingPPPoEnecessarydrivers Dvcrvr> eieDies Ntokdvcupr> ewreiespot <>PP(onopitpooo)spot *Ppittonrtclupr <>PPspotfraycsraot *Puprosneilprs <>PPspotfrsntot *Puproyctyprs

Thetwocompressionoptionswon'tharmbutarenotdefinitelyneeded,neitherdoestheP P o e t e n t PvrEhre option,thatmightonlybeusedbyp p p whenconfiguredtodokernelmodePPPoE. Ifyourequireit,don'tforgettoincludesupportinthekernelforyourethernetcard. IfyouhaveamultiCPUOpteronoramulticore(e.g.AMD64X2)system,youshouldactivate"Symmetricmulti processingsupport":

CodeListing3.6:ActivatingSMPsupport Poesrtpnetrs> rcsoyeadfaue []Smercmlipoesnupr *ymtiutrcsigspot Note:Inmulticoresystems,eachcorecountsasoneprocessor.

IfyouuseUSBInputDevices(likeKeyboardorMouse)don'tforgettoenablethoseaswell:
CodeListing3.7:ActivatingUSBSupportforInputDevices Dvcrvr> eieDies []HDDvcs> *Ieie <>UBHmnItraeDvcflI)spot *Suanefceie(ulHDupr

CompilingandInstalling
Nowthatyourkernelisconfigured,itistimetocompileandinstallit.Exittheconfigurationandstartthecompilation process:
CodeListing3.8:Compilingthekernel #mk&mkoue_ntl ae&aemdlsisal

Whenthekernelhasfinishedcompiling,copythekernelimageto/ o t b o .Usewhatevernameyoufeelis appropriateforyourkernelchoiceandrememberitasyouwillneeditlateronwhenyouconfigureyourbootloader. Remembertoreplacek r e . . 4 g n o 1 e n l 2 6 3 e t o r withthenameandversionofyourkernel.

CodeListing3.9:Installingthekernel #crhx66/otbIae/otkre..4gno1 pac/8_4bo/zmgbo/enl263etor

(Optional)BuildinganInitramfs
Ifyouuseaspecificpartitionlayoutwhereimportantfilesystemlocations(like/ s or/ a )areonseparate ur vr partitions,thenyouwillneedtosetupaninitramfssothatthispartitioncanbemountedbeforeitisneeded.

Withoutaninitramfs,youriskthatthesystemwillnotbootupproperlyasthetoolsthatareresponsibleformounting thefilesystemsneedinformationthatresidesonthosefilesystems.Aninitramfswillpullinthenecessaryfilesinto anarchivewhichisusedrightafterthekernelboots,butbeforethecontrolishandedovertothei i tool.Scripts nt ontheinitramfswillthenmakesurethatthepartitionsareproperlymountedbeforethesystemcontinuesbooting. Toinstallaninitramfs,installg n e n l e k r e first,thenhaveitgenerateaninitramfsforyou.

CodeListing3.10:Buildinganinitramfs #eegekre mregnenl #gnenlisaliirms ekrentlntaf

Ifyouneedspecificsupportintheinitramfs,suchaslvmorraid,addintheappropriateoptionstogenkernel.See g n e n l h l formoreinformation,orthenextexamplewhichenablessupportforLVMandsoftwareraid ekreep (mdadm):

CodeListing3.11:BuildinganinitramfswithsupportforLVMandsoftwareraid #gnenllmmamisaliirms ekrevddntlntaf

Theinitramfswillbestoredin/ o t b o .Youcanfindthefilebysimplylistingthefilesstartingwithi i r m s ntaf:

CodeListing3.12:Checkingtheinitramfsfilename #lbo/ntaf* s/otiirms

NowcontinuewithKernelModules.

7.d.Alternative:Usinggenkernel
Ifyouarereadingthissection,youhavechosentouseourg n e n l e k r e scripttoconfigureyourkernelforyou. Nowthatyourkernelsourcetreeisinstalled,it'snowtimetocompileyourkernelbyusingourg n e n l e k r e scriptto automaticallybuildakernelforyou.g n e n l e k r e worksbyconfiguringakernelnearlyidenticallytothewayour InstallationCDkernelisconfigured.Thismeansthatwhenyouuseg n e n l e k r e tobuildyourkernel,yoursystem willgenerallydetectallyourhardwareatboottime,justlikeourInstallationCDdoes.Becausegenkerneldoesn't requireanymanualkernelconfiguration,itisanidealsolutionforthoseuserswhomaynotbecomfortable compilingtheirownkernels. Now,let'sseehowtousegenkernel.First,emergethegenkernelebuild:
CodeListing4.1:Emerginggenkernel #eegekre mregnenl

Now,compileyourkernelsourcesbyrunningg n e n l a l e k r e l .Beawarethough,asg n e n l e k r e compilesa kernelthatsupportsalmostallhardware,thiscompilationwilltakequiteawhiletofinish! Notethat,ifyourbootpartitiondoesn'tuseext2orext3asfilesystemyoumightneedtomanuallyconfigureyour kernelusingg n e n l m n c n i l andaddsupportforyourfilesysteminthekernel(i.e.notasa ekreeuofgal module).UsersofLVM2willprobablywanttoadd l m asanargumentaswell. v2
CodeListing4.2:Runninggenkernel #gnenlal ekrel

Onceg n e n l e k r e completes,akernel,fullsetofmodulesandinitialramdisk(initramfs)willbecreated.Wewill usethekernelandinitrdwhenconfiguringabootloaderlaterinthisdocument.Writedownthenamesofthekernel andinitrdasyouwillneeditwhenwritingthebootloaderconfigurationfile.Theinitrdwillbestartedimmediately afterbootingtoperformhardwareautodetection(justlikeontheInstallationCD)beforeyour"real"systemstartsup.

CodeListing4.3:Checkingthecreatedkernelimagenameandinitrd #lbo/enlbo/ntaf* s/otkre*/otiirms

7.e.KernelModules ConfiguringtheModules
Youshouldlistthemodulesyouwantautomaticallyloadedin/ t / o f d m d l s e c c n . / o u e .Youcanaddextra optionstothemodulestooifyouwant. Toviewallavailablemodules,runthefollowingf n command.Don'tforgettosubstitute"<kernelversion>"with id theversionofthekernelyoujustcompiled:
CodeListing5.1:Viewingallavailablemodules #fnlbmdls<enlvrin/yefnm*ooiae'.oes id/i/oue/kreeso>tpiae'.'rnm*k'|ls

Forinstance,toautomaticallyloadthe3 5 x k module(whichisthedriverforaspecific3Comnetworkcard c9.o family),editthe/ t / o f d m d l s e c c n . / o u e fileandenterthemodulenameinit.

CodeListing5.2:Editing/etc/conf.d/modules #nnw/t/ofdmdls aoeccn./oue mdls26"c9" oue__=35x

ContinuetheinstallationwithConfiguringyourSystem.

8.ConfiguringyourSystem
8.a.FilesystemInformation Whatisfstab?
UnderLinux,allpartitionsusedbythesystemmustbelistedin/ t / s a .Thisfilecontainsthemountpointsof ecftb thosepartitions(wheretheyareseeninthefilesystemstructure),howtheyshouldbemountedandwithwhat specialoptions(automaticallyornot,whetheruserscanmountthemornot,etc.)

Creating/etc/fstab
/ t / s a usesaspecialsyntax.Everylineconsistsofsixfields,separatedbywhitespace(space(s),tabsora ecftb mixture).Eachfieldhasitsownmeaning: Thefirstfieldshowsthepartitiondescribed(thepathtothedevicefile) Thesecondfieldshowsthemountpointatwhichthepartitionshouldbemounted Thethirdfieldshowsthefilesystemusedbythepartition Thefourthfieldshowsthemountoptionsusedbym u t o n whenitwantstomountthepartition.Asevery filesystemhasitsownmountoptions,youareencouragedtoreadthemountmanpage(m n m u t a o n )fora fulllisting.Multiplemountoptionsarecommaseparated. Thefifthfieldisusedbyd m todetermineifthepartitionneedstobedumpedornot.Youcangenerally up leavethisas0 (zero). Thesixthfieldisusedbyf c todeterminetheorderinwhichfilesystemsshouldbecheckedifthesystem sk wasn'tshutdownproperly.Therootfilesystemshouldhave1 whiletherestshouldhave2 (or0 ifa filesystemcheckisn'tnecessary).
Important:Thedefault/ t / s a fileprovidedbyGentooisnotavalidfstabfile.Youhavetocreateyourown/ t / s a . ecftb ecftb CodeListing1.1:Opening/etc/fstab #nnw/t/sa aoecftb

Letustakealookathowwewritedowntheoptionsforthe/ o t b o partition.Thisisjustanexample,ifyoudidn'tor couldn'tcreatea/ o t b o ,don'tcopyit. InourdefaultAMD64partitioningexample,/ o t b o isusuallythe/ e / d 1 d v s a partition,withe t asfilesystem.It x2

needstobecheckedduringboot,sowewouldwritedown:
CodeListing1.2:Anexample/bootlinefor/etc/fstab /e/d1/otetdfut12 dvsabox2eals

Someusersdon'twanttheir/ o t b o partitiontobemountedautomaticallytoimprovetheirsystem'ssecurity.Those peopleshouldsubstituted f u t withn a t .Thisdoesmeanthatyouneedtomanuallymountthispartition eals ouo everytimeyouwanttouseit. AddtherulesthatmatchyourpartitioningschemeandappendrulesforyourCDROMdrive(s),andofcourse,ifyou haveotherpartitionsordrives,forthosetoo. Nowusetheexamplebelowtocreateyour/ t / s a : ecftb
CodeListing1.3:Afull/etc/fstabexample /e/d1/otx2ealsnaie12 dvsaboetdfut,otm /e/d2nnwpw00 dvsaoesas /e/d3/x3otm01 dvsaetnaie /e/do/n/douoououe00 dvcrmmtcrmatnat,sr

a t makesm u t uo o n guessforthefilesystem(recommendedforremovablemediaastheycanbecreatedwithone ofmanyfilesystems)andu e makesitpossiblefornonrootuserstomounttheCD. sr Toimproveperformance,mostuserswouldwanttoaddthen a i e o t m mountoption,whichresultsinafaster systemsinceaccesstimesaren'tregistered(youdon'tneedthosegenerallyanyway). Doublecheckyour/ t / s a ,saveandquittocontinue. ecftb

8.b.NetworkingInformation Hostname,Domainname,etc
Oneofthechoicestheuserhastomakeisnamehis/herPC.Thisseemstobequiteeasy,butlotsofusersare havingdifficultiesfindingtheappropriatenamefortheirLinuxpc.Tospeedthingsup,knowthatanynameyou choosecanbechangedafterwards.Forallwecare,youcanjustcallyoursystemt x u anddomainh m n t o k oeewr.
CodeListing2.1:Settingthehostname #nnw/t/ofdhsnm aoeccn./otae (ehotaevraloyuotnm) Sttehsnmaibetorhsae hsnm=tx otae"u"

Second,ifyouneedadomainname,setitin/ t / o f d n t e c c n . / e .YouonlyneedadomainifyourISPornetwork administratorsaysso,orifyouhaveaDNSserverbutnotaDHCPserver.Youdon'tneedtoworryaboutDNSor domainnamesifyournetworkingissetupforDHCP.

CodeListing2.2:Settingthedomainname #nnw/t/ofdnt aoeccn./e (ehn_oanvraloyuoannm) Sttedsdmiaibetordmiae dsdmi_o"oeewr" n_oanl=hmntok Note:Ifyouchoosenottosetadomainname,youcangetridofthe"Thisishostname.(none)"messagesatyourloginscreenby editing/ t / s u .Justdeletethestring. O ecise \ fromthatfile.

IfyouhaveaNISdomain(ifyoudon'tknowwhatthatis,thenyoudon'thaveone),youneedtodefinethatonetoo:
CodeListing2.3:SettingtheNISdomainname #nnw/t/ofdnt aoeccn./e

(ehi_oanvraloyuIoannm) SttensdmiaibetorNSdmiae nsdmi_o"ynsoan i_oanl=midmi" Note:FormoreinformationonconfiguringDNSandNIS,pleasereadtheexamplesprovidedin/ s / h r / o / p n c ursaedcoer *nteapeb2 / e . x m l . z whichcanbereadusingb l s .Also,youmaywanttoemergeo e r s l tohelpmanageyour zes pneov DNS/NISsetup.

ConfiguringyourNetwork
Beforeyougetthat"Hey,we'vehadthatalready"feeling,youshouldrememberthatthenetworkingyousetupin thebeginningoftheGentooinstallationwasjustfortheinstallation.Rightnowyouaregoingtoconfigure networkingforyourGentoosystempermanently.
Note:Moredetailedinformationaboutnetworking,includingadvancedtopicslikebonding,bridging,802.1QVLANsorwireless networkingiscoveredintheGentooNetworkConfigurationsection.

Allnetworkinginformationisgatheredin/ t / o f d n t e c c n . / e .Itusesastraightforwardyetnotintuitivesyntaxif youdon'tknowhowtosetupnetworkingmanually.Butdon'tfear,we'llexplaineverything.Afullycommented examplethatcoversmanydifferentconfigurationsisavailablein/ s / h r / o / p n c ursaedcoer *nteapeb2 /e.xml.z. DHCPisusedbydefault.ForDHCPtowork,youwillneedtoinstallaDHCPclient.Thisisdescribedlaterin InstallingNecessarySystemTools.DonotforgettoinstallaDHCPclient. IfyouneedtoconfigureyournetworkconnectioneitherbecauseyouneedspecificDHCPoptionsorbecauseyoudo notuseDHCPatall,open/ t / o f d n t e c c n . / e withyourfavoriteeditor(n n isusedinthisexample): ao
CodeListing2.4:Opening/etc/conf.d/netforediting #nnw/t/ofdnt aoeccn./e

Youwillseethefollowingfile:
CodeListing2.5:Default/etc/conf.d/net #TilnofgrtoilatmtclyueDCone. hsbakcniuainwluoaialsHPfraynt* #srpsiecii..ocetoecmltofgrto, citn/t/ntdTraeamropeecniuain #peseiw/s/hr/o/pnc*nteapeb2adsv laerveursaedcoer/e.xml.znae #yuofgrton/t/ofdnt(hsfl]) orcniuainieccn./etiie:!.

ToenteryourownIPaddress,netmaskandgateway,youneedtosetbothc n i _ t 0 o f g e h andr u e _ t 0 otseh:

CodeListing2.6:ManuallysettingIPinformationforeth0 cni_t0"9.6..ems5.5.5.r9.6..5" ofgeh=121802ntak2525250bd1218025 rue_t0"eali9.6.." otseh=dfutva121801

TouseDHCP,definec n i _ t 0 ofgeh:
CodeListing2.7:AutomaticallyobtaininganIPaddressforeth0 cni_t0"hp ofgeh=dc"

Pleaseread/ s / h r / o / p n c * n t e a p e b 2 u r s a e d c o e r / e . x m l . z foralistofallavailableoptions.Besuretoalso readyourDHCPclientmanpageifyouneedtosetspecificDHCPoptions. Ifyouhaveseveralnetworkinterfacesrepeattheabovestepsforc n i _ t 1 o f g e h ,etc. o f g e h ,c n i _ t 2 Nowsavetheconfigurationandexittocontinue.

AutomaticallyStartNetworkingatBoot
Tohaveyournetworkinterfacesactivatedatboot,youneedtoaddthemtothedefaultrunlevel.

CodeListing2.8:Addingnet.eth0tothedefaultrunlevel #cecii. d/t/ntd #lsntle.t0 ne.onteh #rpaeadnteheal cudtde.t0dfut

Ifyouhaveseveralnetworkinterfaces,youneedtocreatetheappropriaten t e h ,n t e h etc.justlikeyou e.t1 e.t2 didwithn t e h . e.t0

WritingDownNetworkInformation
YounowneedtoinformLinuxaboutyournetwork.Thisisdefinedin/ t / o t andhelpsinresolvinghost echss namestoIPaddressesforhoststhataren'tresolvedbyyournameserver.Youneedtodefineyoursystem.Youmay alsowanttodefineothersystemsonyournetworkifyoudon'twanttosetupyourowninternalDNSsystem.
CodeListing2.9:Opening/etc/hosts #nnw/t/ot aoechss CodeListing2.10:Fillinginthenetworkinginformation (hsdfnstecretsse) Tieiehurnytm 17001txhmntoktxlclot 2...u.oeewruoahs (eieetassesoorntok Dfnxrytmnyuewr, teedtaeasaiPtedfndtia. hyneohvttcIobeiehswy) 121805jnyhmntokjny 9.6..en.oeewren 121806bnyhmntokbny 9.6..en.oeewren

Saveandexittheeditortocontinue. Ifyoudon'thavePCMCIA,youcannowcontinuewithSystemInformation.PCMCIAusersshouldreadthe followingtopiconPCMCIA.

Optional:GetPCMCIAWorking
PCMCIAusersshouldfirstinstallthep m i u i s c c a t l package.
CodeListing2.11:Installingpcmciautils #eegccatl mrepmiuis

8.c.SystemInformation RootPassword
Firstwesettherootpasswordbytyping:
CodeListing3.1:Settingtherootpassword #psw asd

SystemInformation
Gentoouses/ t / c c n toconfiguretheservices,startup,andshutdownofyoursystem.Openup ecr.of / t / c c n andenjoyallthecommentsinthefile. ecr.of
CodeListing3.2:Configuringservices #nnw/t/ccn aoecr.of

Whenyou'refinishedconfiguringthesetwofiles,savethemandexit. Gentoouses/ t / o f d k y a s e c c n . / e m p tohandlekeyboardconfiguration.Editittoconfigureyourkeyboard.

CodeListing3.3:Opening/etc/conf.d/keymaps #nnw/t/ofdkyas aoeccn./emp

Takespecialcarewiththek y a variable.Ifyouselectthewrongk y a ,youwillgetweirdresultswhentyping emp emp onyourkeyboard. Whenyou'refinishedconfiguring/ t / o f d k y a s e c c n . / e m p ,saveandexit. Gentoouses/ t / o f d h c o k e c c n . / w l c tosetclockoptions.Edititaccordingtoyourneeds.
CodeListing3.4:Opening/etc/conf.d/hwclock #nnw/t/ofdhcok aoeccn./wlc

IfyourhardwareclockisnotusingUTC,youneedtoaddc o k " o a " l c = l c l tothefile.Otherwiseyouwillnotice someclockskew. Whenyou'refinishedconfiguring/ t / o f d h c o k e c c n . / w l c ,saveandexit. Youshoulddefinethetimezonethatyoupreviouslycopiedto/ t / o a t m inthe/ t / i e o e eclclie e c t m z n fileso thatfurtherupgradesofthes s l b / i e o e d t packagecanupdate/ t / o a t m automatically. yistmznaa eclclie Forinstance,ifyouusedtheEurope/Brusselstimezone,youwouldwriteE r p / r s e s u o e B u s l inthe /t/ieoe e c t m z n file.

Configurelocales
Youwillprobablyonlyuseoneormaybetwolocalesonyoursystem.Youhavetospecifylocalesyouwillneedin /t/oaegn eclcl.e.
CodeListing3.5:Opening/etc/locale.gen #nnw/t/oaegn aoeclcl.e

ThefollowinglocalesareanexampletogetbothEnglish(UnitedStates)andGerman(Germany)withthe accompanyingcharacterformats(likeUTF8).
CodeListing3.6:Specifyyourlocales e_SIO85 nUS891 e_SUF8UF8 nU.TT d_EIO85 eDS891 d_EerS891 eD@uoIO855 Note:Youcanselectyourdesiredlocalesinthelistgivenbyrunningl c l a oae. Warning:WestronglysuggestthatyoushoulduseatleastoneUTF8localebecausesomeapplicationsmayrequireit.

Thenextstepistorunl c l e .Itwillgeneratesallthelocalesyouhavespecifiedinthe oaegn /t/oaegn e c l c l . e file.

CodeListing3.7:Runninglocalegen #lcle oaegn

Oncedone,younowhavethepossibilitytosetthesystemwidelocalesettingsinthe/ t / n . / 2 o a e ecevd0lcl file:

CodeListing3.8:Settingthedefaultsystemlocalein/etc/env.d/02locale LN=d_EUF8 AG"eD.T" L_OLT=C CCLAE""

Andreloadyourenvironment:

CodeListing3.9:Reloadshellenvironment #evudt&sucecpoie npae&ore/t/rfl

WemadeafullLocalizationGuidetohelpyouthroughthisprocess.YoucanalsoreadourdetailedUTF8Guidefor veryspecificinformationstoenableUTF8onyoursystem. PleasecontinuewithInstallingNecessarySystemTools.

9.InstallingNecessarySystemTools
9.a.SystemLogger
Sometoolsaremissingfromthestage3archivebecauseseveralpackagesprovidethesamefunctionality.Itisnow uptoyoutochoosewhichonesyouwanttoinstall. Thefirsttoolyouneedtodecideonhastoprovideloggingfacilitiesforyoursystem.UnixandLinuxhavean excellenthistoryofloggingcapabilitiesifyouwantyoucanlogeverythingthathappensonyoursysteminlogfiles. Thishappensthroughthesystemlogger. Gentoooffersseveralsystemloggerstochoosefrom.Thereares s l g ,whichisthetraditionalsetofsystem ykod loggingdaemons,s s o g y l g n ,anadvancedsystemlogger,andm t l g e a o whichisahighlyconfigurablesystem logger.OthersmightbeavailablethroughPortageaswellournumberofavailablepackagesincreasesonadaily basis. Ifyouplanonusings s l g ors s o g ykod y l g n youmightwanttoinstalll g o a e o r t t afterwardsasthosesystem loggersdon'tprovideanyrotationmechanismforthelogfiles. Toinstallthesystemloggerofyourchoice,e e g itandhaveitaddedtothedefaultrunlevelusingr p a e mre cudt. Thefollowingexampleinstallss s o g y l g n .Ofcoursesubstitutewithyoursystemlogger:
CodeListing1.1:Installingasystemlogger #eegylgn mressog #rpaeadssogdfut cudtdylgneal

9.b.Optional:CronDaemon
Nextisthecrondaemon.Althoughitisoptionalandnotrequiredforyoursystem,itiswisetoinstallone.Butwhat isacrondaemon?Acrondaemonexecutesscheduledcommands.Itisveryhandyifyouneedtoexecutesome commandregularly(forinstancedaily,weeklyormonthly). Gentoooffersthreepossiblecrondaemons:d r n c o andv x e c o .Installingoneofthemissimilarto c o ,f r n iirn installingasystemlogger.However,d r n c o andf r n c o requireanextraconfigurationcommand,namelyc o t b rna / t / r n a .Ifyoudon'tknowwhattochoose,usev x e c o . eccotb iirn Weonlyprovidev x e c o fornetworklessinstallations.Ifyouwantanothercrondaemonyoucanwaitand iirn installitlateron.
CodeListing2.1:Installingacrondaemon #eegiirn mrevxeco #rpaeadvxecoeal cudtdiirndfut (nyioaecoecorfrnrnaeccotb Olfyuhvhsndrnoco)#cotb/t/rna

9.c.Optional:FileIndexing
Ifyouwanttoindexyoursystem'sfilessoyouareabletoquicklylocatethemusingthel c t tool,youneedto oae installs s a p / l c t . ypsmoae
CodeListing3.1:Installingmlocate #eeglct mremoae

9.d.Optional:RemoteAccess
Ifyouneedtoaccessyoursystemremotelyafterinstallation,don'tforgettoadds h tothedefaultrunlevel: sd
CodeListing4.1:Addingsshdtothedefaultrunlevel #rpaeadsheal cudtdsddfut

Ifyouneedserialconsoleaccess(whichispossibleincaseofremoteservers),you'llneedtouncommenttheserial consolesectionin/ t / n t a . eciitb

CodeListing4.2:Editing/etc/inittab #nnw/t/nta aoeciitb

Thefollowingexcerptshowstheuncommentedsection:
CodeListing4.3:Uncommentingserialconsolesininittab #SRAOSLS EILCNOE s:24:epw:si/gty90tSt0 0135rsan/bnaet60ty0v10 s:24:epw:si/gty90tSt0 1135rsan/bnaet60ty1v10

9.e.FileSystemTools
Dependingonwhatfilesystemsyouareusing,youneedtoinstallthenecessaryfilesystemutilities(forchecking thefilesystemintegrity,creatingadditionalfilesystemsetc.).Pleasenotethattoolsformanagingext2/ext3 filesystems(e f p o s 2 s r g )arealreadyinstalledasapartofthesystem. Thefollowingtableliststhetoolsyouneedtoinstallifyouuseacertainfilesystem:
FileSystem XFS ReiserFS JFS Tool xfsprogs reiserfsprogs jfsutils InstallCommand
eegfpos mrexsrg eegesrsrg mreriefpos eegfuis mrejstl

9.f.NetworkingTools
Ifyoudon'trequireanyadditionalnetworkingrelatedtools(suchasppporadhcpclient)continuewithConfiguring theBootloader.

Optional:InstallingaDHCPClient
IfyourequireGentootoautomaticallyobtainanIPaddressforyournetworkinterface(s),youneedtoinstall d c c (oranyotherDHCPclientseeModularNetworkingforalistofavailableDHCPclients).Ifyoudon'tdo hpd thisnow,youmightnotbeabletoconnecttotheinternetaftertheinstallation.
CodeListing6.1:Installingdhcpcd #eeghpd mredcc

Optional:InstallingaPPPoEClient
Ifyouneedp p p toconnecttothenet,youneedtoinstallit.
CodeListing6.2:Installingppp #eegp mrepp

NowcontinuewithConfiguringtheBootloader.

10.ConfiguringtheBootloader

10.a.MakingyourChoice Introduction
Nowthatyourkernelisconfiguredandcompiledandthenecessarysystemconfigurationfilesarefilledincorrectly, itistimetoinstallaprogramthatwillfireupyourkernelwhenyoustartthesystem.Suchaprogramiscalleda bootloader. ForAMD64,GentooLinuxprovidesGRUBandLILO. Butbeforeweinstallthebootloader,weinformyouhowtoconfigureframebuffer(assumingyouwantitofcourse). WithframebufferyoucanruntheLinuxcommandlinewith(limited)graphicalfeatures(suchasusingthenice bootsplashimageGentooprovides).

Optional:Framebuffer
Ifyouhaveconfiguredyourkernelwithframebuffersupport(oryouusedg n e n l e k r e defaultkernelconfiguration), youcanactivateitbyaddingaav d o i e statementtoyourbootloaderconfigurationfile. Firstofall,youneedtoknowyourframebufferdevice.Youshouldhaveusedu e a b v s f astheVESAdriver. Thev d o i e statementcontrolsframebufferdisplayoptions.Itneedstobegiventheframebufferdriverfollowedby thecontrolstatementsyouwishtoenable.Allvariablesarelistedin /s/r/iu/ouetto/bueabtt u r s c l n x D c m n a i n f / v s f . x .Themostusedoptionsare:
Control ywrap mtrr:n Description Assumethatthegraphicalcardcanwraparounditsmemory(i.e.continueatthebeginningwhenithasapproachedthe end) SetupMTRRregisters.n canbe: 0disabled 1uncachable 2writeback 3writecombining 4writethrough Setuptheresolution,colordepthandrefreshrate.Forinstance,1 2 x 6 2 8 foraresolutionof1024x768,32bit 04783@5 colordepthandarefreshrateof85Hz.

md oe

Theresultcouldbesomethinglikev d o u e a b m r : , w a , 0 4 7 8 3 @ 5 i e = v s f : t r 3 y r p 1 2 x 6 2 8 .Writethissetting downyouwillneeditshortly. NowcontinuebyinstallingGRUBorLILO.

10.b.Default:UsingGRUB UnderstandingGRUB'sterminology
ThemostcriticalpartofunderstandingGRUBisgettingcomfortablewithhowGRUBreferstoharddrivesand partitions.YourLinuxpartition/ e / d 1 d v s a willmostlikelybecalled( d , ) h 0 0 underGRUB.Noticethe parenthesesaroundtheh 0 0 d , theyarerequired. Harddrivescountfromzeroratherthan"a"andpartitionsstartatzeroratherthanone.Beawaretoothatwiththe hddevices,onlyharddrivesarecounted,notatapiidedevicessuchascdromplayersandburners.Also,thesame constructisusedwithSCSIdrives.(NormallytheygethighernumbersthanIDEdrivesexceptwhentheBIOSis configuredtobootfromSCSIdevices.)WhenyouasktheBIOStobootfromadifferentharddisk(forinstanceyour primaryslave),thatharddiskisseenash 0 d. Assumingyouhaveaharddriveon/ e / d andtwomoreon/ e / d and/ e / d ,/ e / d 7 dvsa dvsb d v s c d v s b gets translatedto( d , ) h 1 6 .Itmightsoundtrickyandtrickyitisindeed,butaswewillsee,GRUBoffersatab completionmechanismthatcomeshandyforthoseofyouhavingalotofharddrivesandpartitionsandwhoarea littlelostintheGRUBnumberingscheme. Havinggottenthefeelforthat,itistimetoinstallGRUB.

InstallingGRUB
ToinstallGRUB,let'sfirstemergeit:
Important:Ifyouareusinganonmultilibprofile,youshouldnotemergeg u ,butinsteadyoushouldemergeg u t t c rb r b s a i .If youplantouseanonmultilibprofileandyouhavedisabledIA32emulationinyourkernel,thenyoushouldusel l . io CodeListing2.1:InstallingGRUB #eegrb mregu

AlthoughGRUBisnowinstalled,westillneedtowriteupaconfigurationfileforitandplaceGRUBinourMBRso thatGRUBautomaticallybootsyournewlycreatedkernel.Create/ o t g u / r b c n withn n (or,if bo/rbgu.of ao applicable,anothereditor):

CodeListing2.2:Creating/boot/grub/grub.conf #nnw/otgu/rbcn aobo/rbgu.of

Nowwearegoingtowriteupag u . o f r b c n .Makesureyouuseyourkernelimagefilenameand,ifappropriate, yourinitrdimagefilename.

Note:GrubassignsdevicedesignationsfromtheBIOS.IfyouchangeyourBIOSsettings,yourdevicelettersandnumbersmay change,too.Forexample,ifyouchangeyourdevicebootorder,youmayneedtochangeyourgrubconfiguration. Note:IfyourrootfilesystemisJFS,youmustadd"ro"tothek r e linesinceJFSneedstoreplayitslogbeforeitallowsread enl writemounting. CodeListing2.3:Examplegrub.conf #Wihlsigtotaeal.0ihis,1tescnt. hcitnobosdfutstefrtheodec dfut0 eal #Hwmneodowieoetedfutlsigiotd oayscnstatbfrhealitnsboe. tmot3 ieu0 #Nc,ftslsmgosietigp: ieapahiaetpchnsu) #Cmetotioo'aeagahcadisald omnufyudnthvrpiscrntle slsiae(d,)bo/rbsls.p.z pahmg=h00/otgu/pahxmg tteGnoiu..4r iletoLnx2631 #Priinweetekremgoprtnytmslctd attohrhenliae(roeaigsse)ioae roh00 ot(d,) krebo/enl263etorot/e/d3 enl/otkre..4gno1ro=dvsa tteGnoiu..4rrsu) iletoLnx2631(ece #Priinweetekremgoprtnytmslctd attohrhenliae(roeaigsse)ioae roh00 ot(d,) krebo/enl263etorot/e/d3ii=bnb enl/otkre..4gno1ro=dvsant/i/b #TenxorlnsaeolfyudaboihaWnossse. hetfuiernyioulotwtidwytm #Ihscs,Wnosiotdodvsa. ntiaeidwshsen/e/d6 tteWnosX ilidwP ronvrfh05 otoeiy(d,) mkatv aecie canodr+ hilae1

If,whilebuildingtheLinuxkernel,youoptedtoincludeaninitramfstobootfrom,thenyouwillneedtochangethe configurationbyreferringtothisinitramfsfileandtellingtheinitramfswhereyourrealrootdeviceisat:
CodeListing2.4:GRUBsnippetforinitramfsenabledkernelbuilds tteGnoiu..4r iletoLnx2631 roh00 ot(d,) krebo/..4relro=dvsa enl/ot2631ra_ot/e/d3 iirbo/ntafekrem6..4gno1 ntd/otiirmsgnenlad4263etor

Ifyouusedadifferentpartitioningschemeand/orkernelimage,adjustaccordingly.However,makesurethat anythingthatfollowsaGRUBdevice(suchas( d , ) h 0 0 )isrelativetothemountpoint,nottheroot.Inotherwords, ( d , ) g u / p a h x m g isinreality/ o t g u / p a h x m g since( d , ) h00/rbsls.p.z bo/rbsls.p.z h 0 0 is/ o t bo. Besides,ifyouchosetouseadifferentpartitioningschemeanddidnotput/ o t b o inaseparatepartition,the /ot b o prefixusedintheabovecodesamplesisreallyrequired.Ifyoufollowedoursuggestedpartitioningplan,the /ot b o prefixitnotrequired,butab o symlinkmakesitwork.Inshort,theaboveexamplesshouldworkwhether ot youdefinedaseparate/ o t b o partitionornot. Ifyouneedtopassanyadditionaloptionstothekernel,simplyaddthemtotheendofthekernelcommand.We're alreadypassingoneoption(r o = d v s a orr a _ o t / e / d 3 ot/e/d3 e l r o = d v s a ),butyoucanpassothersaswell, suchasthev d o i e statementforframebufferaswediscussedpreviously. Ifyourbootloaderconfigurationfilecontainsthereal_rootparameter,usethereal_rootflagsparametertosetroot filesystemmountoptions. Ifyou'reusinga2.6.7orhigherkernelandyoujumperedyourharddrivebecausetheBIOScan'thandlelarge harddrivesyou'llneedtoappends a s r k .Replacesdawiththedevicethatrequiresthisoption. d=toe gnenl e k r e usersshouldknowthattheirkernelsusethesamebootoptionsasisusedfortheInstallationCD.For instance,ifyouhaveSCSIdevices,youshouldaddd s s askerneloption. oci Nowsavetheg u . o f r b c n fileandexit.YoustillneedtoinstallGRUBintheMBR(MasterBootRecord)sothat GRUBisautomaticallyexecutedwhenyoubootyoursystem. TheGRUBdevelopersrecommendtheuseofg u n t l .However,ifforsomereasong u n t l fails rbisal rbisal toworkcorrectlyyoustillhavetheoptiontomanuallyinstallGRUB. ContinuewithDefault:SettingupGRUBusinggrubinstallorAlternative:SettingupGRUBusingmanual instructions.

Default:SettingupGRUBusinggrubinstall
ToinstallGRUByouwillneedtoissuetheg u n t l command.However,g u n t l won'tworkoff rbisal rbisal theshelfsinceweareinsideachrootedenvironment.Weneedtocreate/ t / t b e c m a whichlistsallmounted filesystems.Fortunately,thereisaneasywaytoaccomplishthisjustcopyover/ r c m u t to/ t / t b po/ons ecma, excludingther o f lineifyouhaven'tcreatedaseparatebootpartition.Thefollowingcommandwillworkinboth ots cases:
CodeListing2.5:Creating/etc/mtab #gevrofpo/ons>/t/tb rpots/rcmutecma

NowwecaninstallGRUBusingg u n t l : rbisal
CodeListing2.6:Runninggrubinstall #guntlofopdvsa rbisalnlpy/e/d

IfyouhavemorequestionsregardingGRUB,pleaseconsulttheGRUBFAQ,theGRUBWiki,orreadi f r b nogu inyourterminal. ContinuewithRebootingtheSystem.

Alternative:SettingupGRUBusingmanualinstructions
TostartconfiguringGRUB,youtypeing u .You'llbepresentedwiththeg u > rb r b grubcommandlineprompt. Now,youneedtotypeintherightcommandstoinstalltheGRUBbootrecordontoyourharddrive.
CodeListing2.7:StartingtheGRUBshell #guofop rbnlpy Note:Ifyoursystemdoesnothaveanyfloppydrives,addthe n l p y o f o p optiontotheabovecommandtopreventgrubfrom

probingthe(nonexisting)floppydrives.

IntheexampleconfigurationwewanttoinstallGRUBsothatitreadsitsinformationfromthebootpartition /e/d1 d v s a ,andinstallstheGRUBbootrecordontheharddrive'sMBR(masterbootrecord)sothatthefirstthing weseewhenweturnonthecomputeristheGRUBprompt.Ofcourse,ifyouhaven'tfollowedtheexample configurationduringtheinstallation,changethecommandsaccordingly. ThetabcompletionmechanismofGRUBcanbeusedfromwithinGRUB.Forinstance,ifyoutypein"r o " ot( followedbyaTAB,youwillbepresentedwithalistofdevices(suchash 0 d ).Ifyoutypein"r o h 0 " ot(d, followedbyaTAB,youwillreceivealistofavailablepartitionstochoosefrom(suchash 0 0 d , ). Byusingthetabcompletion,settingupGRUBshouldbenotthathard.Nowgoon,configureGRUB,shallwe?:)
CodeListing2.8:InstallingGRUBintheMBR gu>roh00(pcfhror/otpriinrsds rbot(d,)Seiyweeyuboattoeie) gu>stp(d)(ntlRBihB) rbeuh0IsalGUnteMR gu>qi(xtteGUhl) rbutEihRBsel Note:IfyouwanttoinstallGRUBinacertainpartitioninsteadoftheMBR,youhavetoalterthes t p e u commandsoitpointstothe rightpartition.Forinstance,ifyouwantGRUBinstalledin/ e / d 3 d v s a ,thenthecommandbecomess t p ( d , ) e u h 0 2 .Fewusers howeverwanttodothis.

IfyouhavemorequestionsregardingGRUB,pleaseconsulttheGRUBFAQ,theGRUBWiki,orreadi f r b nogu inyourterminal. ContinuewithRebootingtheSystem.

10.c.Alternative:UsingLILO InstallingLILO
LILO,theLInuxLOader,isthetriedandtrueworkhorseofLinuxbootloaders.However,itlackssomefeaturesthat GRUBhas(whichisalsothereasonwhyGRUBiscurrentlygainingpopularity).ThereasonwhyLILOisstillusedis that,onsomesystems,GRUBdoesn'tworkandLILOdoes.Ofcourse,itisalsousedbecausesomepeopleknow LILOandwanttostickwithit.Eitherway,Gentoosupportsboth,andapparentlyyouhavechosentouseLILO. InstallingLILOisabreezejustusee e g . mre
CodeListing3.1:InstallingLILO #eegio mrell

ConfiguringLILO
ToconfigureLILO,youmustcreate/ t / i o c n .Fireupyourfavoriteeditor(inthishandbookweusen n ecll.of ao forconsistency)andcreatethefile.
CodeListing3.2:Creating/etc/lilo.conf #nnw/t/iocn aoecll.of

Somesectionsagowehaveaskedyoutorememberthekernelimagenameyouhavecreated.Inthenextexample ll.of i o c n weusetheexamplepartitioningscheme. Makesureyouuseyourkernelimagefilenameand,ifappropriate,yourinitrdimagefilename.

Note:IfyourrootfilesystemisJFS,youmustaddaa p n = r " p e d " o lineaftereachbootitemsinceJFSneedstoreplayitslog beforeitallowsreadwritemounting. CodeListing3.3:Example/etc/lilo.conf bo=dvsa#IsalLLnteMR ot/e/dntlIOihB pop#Gvhsrtecacoslcnteeto rmtieteuehhneteetaohrscin

tmot5#Wifv)scnsbfrotnhealeto ieu=0at5(ieeodeoeboigtedfutscin dfutgno#Wehieuaasdotte"etoeto eal=etohntetmothspse,bohgno"scin iae/otkre..4gno1 mg=bo/enl263etor lblgno#Nmegvotieto ae=etoaewiethsscin rany#Satwtedolotontatr edoltriharanyro.Dole! ro=dvsa#Lctofteroieytm ot/e/d3oainohotflsse iae/otkre..4gno1 mg=bo/enl263etor lblgno.ece#Nmegvotieto ae=etorsuaewiethsscin rany#Satwtedolotontatr edoltriharanyro.Dole! ro=dvsa#Lctofteroieytm ot/e/d3oainohotflsse apn=ii=bnb"#Luchetosaiecesel ped"nt/i/banhteGnottcrsuhl #Tenxwiernyioulotwtidwytm hettolnsaeolfyudaboihaWnossse. #Ihscs,Wnosiotdodvsa. ntiaeidwshsen/e/d6 ohr/e/d6 te=dvsa lblwnos ae=idw Note:Ifyouuseadifferentpartitioningschemeand/orkernelimage,adjustaccordingly.

If,whilebuildingtheLinuxkernel,youoptedtoincludeaninitramfstobootfrom,thenyouwillneedtochangethe configurationbyreferringtothisinitramfsfileandtellingtheinitramfswhereyourrealrootdeviceisat:
CodeListing3.4:LILOsnippetforinitramfsenabledkernelbuilds iae/otkre..4gno1 mg=bo/enl263etor lblgno ae=eto rany edol ra_ot/e/d3 elro=dvsa iir=bo/ntafekrem6..4gno1 ntd/otiirmsgnenlad4263etor

Ifyouneedtopassanyadditionaloptionstothekernel,addana p n statementtothesection.Asanexample, ped weaddthev d o i e statementtoenableframebuffer:

CodeListing3.5:Usingappendtoaddkerneloptions iae/otkre..4gno1 mg=bo/enl263etor lblgno ae=eto rany edol ro=dvsa ot/e/d3 apn=vdoueabmr,wa,04783@5 ped"ie=vsf:tryrp12x628"

Ifyou'reusinga2.6.7orhigherkernelandyoujumperedyourharddrivebecausetheBIOScan'thandlelarge harddrivesyou'llneedtoappends a s r k .Replacesdawiththedevicethatrequiresthisoption. d=toe gnenl e k r e usersshouldknowthattheirkernelsusethesamebootoptionsasisusedfortheInstallationCD.For instance,ifyouhaveSCSIdevices,youshouldaddd s s askerneloption. oci Nowsavethefileandexit.Tofinishup,youhavetorun/ b n l l soLILOcanapplythe/ t / i o c n si/io ecll.of toyoursystem(i.e.installitselfonthedisk).Keepinmindthatyou'llalsohavetorun/ b n l l everytimeyou si/io installanewkernelormakeanychangestothemenu.
CodeListing3.6:FinishingtheLILOinstallation #/bnll si/io

IfyouhavemorequestionsregardingLILO,pleaseconsultitswikipediapage. YoucannowcontinuewithRebootingtheSystem.

10.d.RebootingtheSystem
Exitthechrootedenvironmentandunmountallmountedpartitions.Thentypeinthatonemagicalcommandyou

havebeenwaitingfor:r b o . eot
CodeListing4.1:Unmountingallpartitionsandrebooting #ei xt ciae~d dmg#c ciae~mutmtgno/e{sm/t, dmg#uonl/n/etodv/h,ps} ciae~mutmtgno{bo,po, dmg#uonl/n/eto/ot/rc} ciae~eot dmg#rbo

Ofcourse,don'tforgettoremovethebootableCD,otherwisetheCDwillbebootedagaininsteadofyournew Gentoosystem. OncerebootedinyourGentooinstallation,finishupwithFinalizingyourGentooInstallation.

11.FinalizingyourGentooInstallation
11.a.UserAdministration AddingaUserforDailyUse
WorkingasrootonaUnix/Linuxsystemisdangerousandshouldbeavoidedasmuchaspossible.Thereforeitis stronglyrecommendedtoaddauserfordaytodayuse. Thegroupstheuserismemberofdefinewhatactivitiestheusercanperform.Thefollowingtablelistsanumberof importantgroupsyoumightwishtouse:
Group audio cdrom floppy games portage usb video wheel Description beabletoaccesstheaudiodevices beabletodirectlyaccessopticaldevices beabletodirectlyaccessfloppydevices beabletoplaygames beabletousee e g r t n asanormaluser mrepeed beabletoaccessUSBdevices beabletoaccessvideocapturinghardwareanddoinghardwareacceleration beabletouses u

Forinstance,tocreateausercalledj h whoismemberofthew e l s r anda d o on h e ,u e s u i groups,loginasroot first(onlyrootcancreateusers)andrunu e a d srd:

CodeListing1.1:Addingauserfordaytodayuse Lgnot oi:ro Pswr:(orroasod asodYuotpswr) #ueadGuesweladobnbson srdmsr,he,uis/i/ahjh #pswon asdjh Pswr:(nehasodfrjh) asodEtrtepswroon RneasodRnehasodteiy eetrpswr:(eetrtepswrovrf)

Ifausereverneedstoperformsometaskasroot,theycanuses totemporarilyreceiverootprivileges.Another u wayistousethes d packagewhichis,ifcorrectlyconfigured,verysecure. uo

11.b.DiskCleanup Removingtarballs
Nowthatyou'vefinishedinstallingGentooandrebooted,ifeverythinghasgonewell,youcanremovethe downloadedstage3tarballandPortagesnapshotfromyourharddisk.Rememberthattheyweredownloadedto your/ directory.
CodeListing2.1:Removingthestage3tarball

#rsae.a.z* m/tg3*trb2 CodeListing2.2:RemovingthePortagesnapshot #rpraelts.a.z* m/otgaettrb2

12.Wheretogofromhere?
12.a.Documentation
Congratulations!YounowhaveaworkingGentoosystem.Butwheretogofromhere?Whatareyouroptionsnow? Whattoexplorefirst?Gentooprovidesitsuserswithlotsofpossibilities,andthereforelotsofdocumented(andless documented)features. YoushoulddefinitelytakealookatthenextpartoftheGentooHandbookentitledWorkingwithGentoowhich explainshowtokeepyoursoftwareuptodate,howtoinstallmoresoftware,whatUSEflagsare,howtheGentoo initsystemworks,etc. Ifyouareinterestedinoptimizingyoursystemfordesktopuse,oryouwanttolearnhowtoconfigureyoursystemto beafullworkingdesktopsystem,consultourextensiveGentooDesktopDocumentationResources.Besides,you mightwanttouseourlocalizationguidetomakeyoursystemfeelmoreathome. WealsohaveaGentooSecurityHandbookwhichisworthreading. ForafulllistingofallouravailabledocumentationcheckoutourDocumentationResourcespage. Finally,wealsohaveanofficialGentooWikiwhereadditional,communityprovideddocumentationcanbefound.

12.b.GentooOnline
YouareofcoursealwayswelcomeonourGentooForumsorononeofourmanyGentooIRCchannels. Wealsohaveseveralmailinglistsopentoallourusers.Informationonhowtojoiniscontainedinthatpage. We'llshutupnowandletyouenjoyyourinstallation.:)

B.WorkingwithGentoo
1.APortageIntroduction
1.a.WelcometoPortage
PortageisprobablyGentoo'smostnotableinnovationinsoftwaremanagement.Withitshighflexibilityand enormousamountoffeaturesitisfrequentlyseenasthebestsoftwaremanagementtoolavailableforLinux. PortageiscompletelywritteninPythonandBashandthereforefullyvisibletotheusersasbotharescripting languages. MostuserswillworkwithPortagethroughthee e g tool.Thischapterisnotmeanttoduplicatetheinformation mre availablefromtheemergemanpage.Foracompleterundownofemerge'soptions,pleaseconsultthemanpage:
CodeListing1.1:Readingtheemergemanpage $mneeg amre

1.b.ThePortageTree Ebuilds
Whenwetalkaboutpackages,weoftenmeansoftwaretitlesthatareavailabletotheGentoousersthroughthe Portagetree.ThePortagetreeisacollectionofebuilds,filesthatcontainallinformationPortageneedstomaintain software(install,search,query,...).Theseebuildsresidein/ s / o t g bydefault. urprae

WheneveryouaskPortagetoperformsomeactionregardingsoftwaretitles,itwillusetheebuildsonyoursystem asabase.ItisthereforeimportantthatyouregularlyupdatetheebuildsonyoursystemsoPortageknowsabout newsoftware,securityupdates,etc.

UpdatingthePortageTree
ThePortagetreeisusuallyupdatedwithrsync,afastincrementalfiletransferutility.Updatingisfairlysimpleasthe e e g commandprovidesafrontendforrsync: mre
CodeListing2.1:UpdatingthePortagetree #eegyc mresn

IfyouareunabletorsyncduetofirewallrestrictionsyoucanstillupdateyourPortagetreebyusingourdaily generatedPortagetreesnapshots.Thee e g e r y c m r e w b s n toolautomaticallyfetchesandinstallsthelatest snapshotonyoursystem:

CodeListing2.2:Runningemergewebrsync #eegeryc mrewbsn

Anadditionaladvantageofusinge e g e r y c m r e w b s n isthatitallowstheadministratortoonlypullinportagetree snapshotsthataresignedbytheGentooreleaseengineeringGPGkey.Moreinformationonthiscanbefoundin thePortageFeaturessectiononFetchingValidatedPortageTreeSnapshots.

1.c.MaintainingSoftware SearchingforSoftware
TosearchthroughthePortagetreeaftersoftwaretitles,youcanusee e g builtinsearchcapabilities.By mre default,e e g e r h m r e s a c returnsthenamesofpackageswhosetitlematches(eitherfullyorpartially)thegiven searchterm. Forinstance,tosearchforallpackageswhohave"pdf"intheirname:
CodeListing3.1:Searchingforpdfnamedpackages $eegerhpf mresacd

Ifyouwanttosearchthroughthedescriptionsaswellyoucanusethe s a c d s (or )switch: erhec S

CodeListing3.2:Searchingforpdfrelatedpackages $eegerhecpf mresacdsd

Whenyoutakealookattheoutput,you'llnoticethatitgivesyoualotofinformation.Thefieldsareclearlylabelled sowewon'tgofurtherintotheirmeanings:
CodeListing3.3:Example'emergesearch'output *ern/uspf ntpitcpd Ltsesovial:152 aetvrinaalbe.. Ltsesontle:[NtIsald] aetvrinisaldontle Szfdwlaeie:1B ieoonoddfls5k Hmpg:tp/cppyi.nurbr.e~rercpd/ oeaeht:/i.hskuiwezugd/vbh/uspf DsrpinrvdsavrulpitrfrCPopouePFfls ecito:PoieitarneoUStrdcDie. LcneP ies:GL2

InstallingSoftware
Onceyou'vefoundasoftwaretitletoyourliking,youcaneasilyinstallitwithe e g :justaddthepackagename. mre Forinstance,toinstallg u e i : nmrc
CodeListing3.4:Installinggnumeric

#eegnmrc mreguei

Sincemanyapplicationsdependoneachother,anyattempttoinstallacertainsoftwarepackagemightresultinthe installationofseveraldependenciesaswell.Don'tworry,Portagehandlesdependencieswell.Ifyouwanttofindout whatPortagewouldinstallwhenyouaskittoinstallacertainpackage,addthe p e e d r t n switch.Forinstance:

CodeListing3.5:Pretendtoinstallgnumeric #eegrtnnmrc mrepeedguei

WhenyouaskPortagetoinstallapackage,itwilldownloadthenecessarysourcecodefromtheinternet(if necessary)andstoreitbydefaultin/ s / o t g / i t i e .Afterthisitwillunpack,compileandinstallthe urpraedsfls package.IfyouwantPortagetoonlydownloadthesourceswithoutinstallingthem,addthe f t h n y e c o l option tothee e g command: mre

CodeListing3.6:Downloadthesourcecodeforgnumeric #eegecolnmrc mrefthnyguei

FindingInstalledPackageDocumentation
Manypackagescomewiththeirowndocumentation.Sometimes,thed c o USEflagdetermineswhetherthe packagedocumentationshouldbeinstalledornot.Youcanchecktheexistenceofad c o USEflagwiththe eegvpcaenm> m r e p < a k g a e command.
CodeListing3.7:CheckingtheexistenceofadocUSEflag (lalbiutaxml,oore) asisjsneapefcus. #eegvlalb mrepasi [bid]mdalb/lalb101_ceudc68k eulNeiisasi..4r1dbg+o9B

Thebestwayofenablingthed c o USEflagisdoingitonaperpackagebasisvia / t / o t g / a k g . s ,sothatyougetdocumentationonlyforpackagesthatyouareinterestedin. ecpraepcaeue Enablingthisflaggloballyisknowntocauseproblemswithcirculardependencies.Formoreinformation,please readtheUSEFlagschapter. Oncethepackageinstalled,itsdocumentationisgenerallyfoundinasubdirectorynamedafterthepackageunder the/ s / h r / o directory.Youcanalsolistallinstalledfileswiththee u r toolwhichispartofthea p ursaedc qey p p r a e g n o l i package. otg/etokt
CodeListing3.8:Locatingpackagedocumentation #ll/s/hr/o/lalb101_c sursaedcasi..4r1 ttl2 oa8 wr1root6a72:4CagLgg rrotro69My115hneo.z wr1root97a72:4CPIGg rrotro33My115OYN.z dwrx2root86a72:4hm rxrxotro50My115tl wr1root9a72:4TD.z rrotro16My115OOg (lentvl,ueeurolctneetnie: Atraieysqeytoaeitrsigfls) #eurielalb|ls qeyflsasies mdalb/lalb101_c eiisasi..4r1 *Cnetfmdalb/lalb101_c: otnsoeiisasi..4r1 /s ur /s/i urbn /s/i/laip urbnasls (upttuctd Oturnae)

RemovingSoftware
Whenyouwanttoremoveasoftwarepackagefromyoursystem,usee e g n e g .ThiswilltellPortage mreumre toremoveallfilesinstalledbythatpackagefromyoursystemexcepttheconfigurationfilesofthatapplicationifyou havealteredthoseaftertheinstallation.Leavingtheconfigurationfilesallowsyoutocontinueworkingwiththe

packageifyoueverdecidetoinstallitagain. However,abigwarningapplies:Portagewillnotcheckifthepackageyouwanttoremoveisrequiredbyanother package.Itwillhoweverwarnyouwhenyouwanttoremoveanimportantpackagethatbreaksyoursystemifyou unmergeit.

CodeListing3.9:Removinggnumericfromthesystem #eegnegnmrc mreumreguei

Whenyouremoveapackagefromyoursystem,thedependenciesofthatpackagethatwereinstalledautomatically whenyouinstalledthesoftwareareleft.TohavePortagelocatealldependenciesthatcannowberemoved,use e e g 's d p l a functionality.Wewilltalkaboutthislateron. mre ecen

UpdatingyourSystem
Tokeepyoursysteminperfectshape(andnottomentioninstallthelatestsecurityupdates)youneedtoupdate yoursystemregularly.SincePortageonlycheckstheebuildsinyourPortagetreeyoufirsthavetoupdateyour Portagetree.WhenyourPortagetreeisupdated,youcanupdateyoursystemwithe e g p a e w r d mreudtol. Inthenextexample,we'llalsousethe a k s switchwhichwilltellPortagetodisplaythelistofpackagesitwants toupgradeandaskyouifyouwanttocontinue:
CodeListing3.10:Updatingyoursystem #eegpaeakwrd mreudtsol

Portagewillthensearchfornewerversionoftheapplicationsyouhaveinstalled.However,itwillonlyverifythe versionsfortheapplicationsyouhaveexplicitlyinstalled(theapplicationslistedin/ a / i / o t g / o l ) vrlbpraewrd itdoesnotthoroughlychecktheirdependencies.Ifyouwanttoupdatethedependenciesofthosepackagesaswell, addthe d e argument: ep

CodeListing3.11:Updatingyoursystemwithdependencies #eegpaedeol mreudtepwrd

Still,thisdoesn'tmeanallpackages:somepackagesonyoursystemareneededduringthecompileandbuild processofpackages,butoncethatpackageisinstalled,thesedependenciesarenolongerrequired.Portagecalls thosebuilddependencies.Toincludethoseinanupdatecycle,add w t d p = : ihbesy

CodeListing3.12:Updatingyourentiresystem #eegpaedeihbesywrd mreudtepwtdp=ol

Sincesecurityupdatesalsohappeninpackagesyouhavenotexplicitlyinstalledonyoursystem(butthatarepulled inasdependenciesofotherprograms),itisrecommendedtorunthiscommandonceinawhile. IfyouhavealteredanyofyourUSEflagslatelyyoumightwanttoadd n w s aswell.Portagewillthenverifyif eue thechangerequirestheinstallationofnewpackagesorrecompilationofexistingones:

CodeListing3.13:Performingafullupdate #eegpaedeihbesynwsol mreudtepwtdp=euewrd

Metapackages
SomepackagesinthePortagetreedon'thaveanyrealcontentbutareusedtoinstallacollectionofpackages.For instance,thek e m t packagewillinstallacompleteKDEenvironmentonyoursystembypullinginvarious dea KDErelatedpackagesasdependencies. Ifyoueverwanttoremovesuchapackagefromyoursystem,runninge e g n e g onthepackagewon't mreumre havemucheffectasthedependenciesremainonthesystem. Portagehasthefunctionalitytoremoveorphaneddependenciesaswell,butsincetheavailabilityofsoftwareis dynamicallydependentyoufirstneedtoupdateyourentiresystemfully,includingthenewchangesyouapplied

whenchangingUSEflags.Afterthisyoucanrune e g e c e n m r e d p l a toremovetheorphaneddependencies. Whenthisisdone,youneedtorebuildtheapplicationsthatweredynamicallylinkedtothenowremovedsoftware titlesbutdon'trequirethemanymore. Allthisishandledwiththefollowingthreecommands:

CodeListing3.14:Removingorphaneddependencies #eegpaedeeuewrd mreudtepnwsol #eegecen mredpla #rveeul edprbid

r v e e u l isprovidedbytheg n o l i packagedon'tforgettoemergeitfirst: edprbid etokt

CodeListing3.15:Installingthegentoolkitpackage #eegetokt mregnoli

1.d.Licenses
BeginningwithPortageversion2.1.7,youcanacceptorrejectsoftwareinstallationbasedonitslicense.All packagesinthetreecontainaL C N E I E S entryintheirebuilds.Runninge e g e r h p c a e a e m r e s a c a k g n m will tellyouthepackage'slicense. Bydefault,Portagepermitsalllicenses,exceptEndUserLicenseAgreements(EULAs)thatrequirereadingand signinganacceptanceagreement. ThevariablethatcontrolspermittedlicensesisA C P _ I E S ,whichcanbesetin/ t / a e c n : CETLCNE ecmk.of
CodeListing4.1:DefaultACCEPT_LICENSEin/etc/make.conf ACP_IES=*EL" CETLCNE"@UA

Withthisconfiguration,packagesthatrequireinteractionduringinstallationtoapprovetheirEULAwillnotbe installed.PackageswithoutanEULAwillbeinstalled. YoucansetA C P _ I E S globallyin/ t / a e c n ,oryoucanspecifyitonaperpackagebasisin CETLCNE ecmk.of /t/otg/akg.ies. ecpraepcaelcne Forexample,ifyouwanttoallowthet u c y t 2 7 r e r p . licensefora p c y t t u c y t p r p / r e r p ,addthefollowingto /t/otg/akg.ies: ecpraepcaelcne
CodeListing4.2:Specifyingatruecryptlicenseinpackage.license apcyttucyttucyt27 prp/rerprerp.

Thispermitsinstallationoftruecryptversionsthathavethet u c y t 2 7 r e r p . license,butnotversionswiththe tucyt28 r e r p . license.

Important:Licensesarestoredin/ s / o t g / i e s s u r p r a e l c n e ,andlicensegroupsarekeptin / s / o t g / r f l s l c n e g o p .ThefirstentryofeachlineinCAPITALlettersisthenameofthelicensegroup, urpraepoie/ies_rus andeveryentryafterthatisanindividuallicense.

LicensegroupsdefinedinA C P _ I E S areprefixedwithan@sign.Here'sanexampleofasystemthat CETLCNE globallypermitstheGPLcompatiblelicensegroup,aswellasafewothergroupsandindividuallicenses:

CodeListing4.3:ACCEPT_LICENSEin/etc/make.conf ACP_IES=@POPTBE@SPRVD@UAahrshlBttemea CETLCNE"GLCMAILOIAPOEELteoaisraVr"

Ifyouwantonlyfreesoftwareanddocumentationonyoursystem,youmightusethefollowingsetup:
CodeListing4.4:Useonlyfreelicenses ACP_IES=FE" CETLCNE"*@RE

Inthiscase,"free"ismostlydefinedbytheFSFandOSI.Anypackagewhoselicensedoesnotmeetthese requirementswillnotbeinstalledonyoursystem.

1.e.WhenPortageisComplaining... AboutSLOTs,Virtuals,Branches,ArchitecturesandProfiles
Aswestatedbefore,Portageisextremelypowerfulandsupportsmanyfeaturesthatothersoftwaremanagement toolslack.Tounderstandthis,weexplainafewaspectsofPortagewithoutgoingintotoomuchdetail. WithPortagedifferentversionsofasinglepackagecancoexistonasystem.Whileotherdistributionstendtoname theirpackagetothoseversions(likef e t p andf e t p 2 reye r e y e )PortageusesatechnologycalledSLOTs.An ebuilddeclaresacertainSLOTforitsversion.EbuildswithdifferentSLOTscancoexistonthesamesystem.For instance,thef e t p packagehasebuildswithS O = 1 andS O = 2 . reye LT"" LT"" Therearealsopackagesthatprovidethesamefunctionalitybutareimplementeddifferently.Forinstance, m t l g ,s s l g ands s o g eaod ykod y l g n areallsystemloggers.Applicationsthatrelyontheavailabilityof"a systemlogger"cannotdependon,forinstance,m t l g ,astheothersystemloggersareasgoodachoiceas eaod any.Portageallowsforvirtuals:eachsystemloggerislistedasaprovideroftheloggingserviceinthel g e ogr virtualpackageofthev r u l i t a category,sothatapplicationscandependonthev r u l l g e package. ita/ogr SoftwareinthePortagetreecanresideindifferentbranches.Bydefaultyoursystemonlyacceptspackagesthat Gentoodeemsstable.Mostnewsoftwaretitles,whencommitted,areaddedtothetestingbranch,meaningmore testingneedstobedonebeforeitismarkedasstable.Althoughyouwillseetheebuildsforthosesoftwareinthe Portagetree,Portagewillnotupdatethembeforetheyareplacedinthestablebranch. Somesoftwareisonlyavailableforafewarchitectures.Orthesoftwaredoesn'tworkontheotherarchitectures,orit needsmoretesting,orthedeveloperthatcommittedthesoftwaretothePortagetreeisunabletoverifyifthe packageworksondifferentarchitectures. EachGentooinstallationadherestoacertainp o i e r f l whichcontains,amongstotherinformation,thelistof packagesthatarerequiredforasystemtofunctionnormally.

BlockedPackages
CodeListing5.1:Portagewarningaboutblockedpackages(withpretend) [lcsB]mit/stilcigmit/oti..1 bokalmasmp(sboknalmapsfx222r) CodeListing5.2:Portagewarningaboutblockedpackages(withoutpretend) !!Errhalmapsfxpcaecnlcswtnteakg. !ro:temit/otiakgofitihaohrpcae !!ohcntbntlentesmytmtgte. !bta'eisaldohaesseoehr !!laeue'mrepeedodtriebokr. !Pesseegrtn'teemnlces

EbuildscontainspecificfieldsthatinformPortageaboutitsdependencies.Therearetwopossibledependencies: builddependencies,declaredinD P N andruntimedependencies,declaredinR E E D EED D P N .Whenoneofthese dependenciesexplicitlymarksapackageorvirtualasbeingnotcompatible,ittriggersablockage. WhilerecentversionsofPortagearesmartenoughtoworkaroundminorblockageswithoutuserintervention, occasionallyyouwillneedtofixityourself,asexplainedbelow. Tofixablockage,youcanchoosetonotinstallthepackageorunmergetheconflictingpackagefirst.Inthegiven example,youcanoptnottoinstallp s f x o t i ortoremoves m p s t first. Youmayalsoseeblockingpackageswithspecificatoms,suchas<mediavideo/mplayer1.0_rc1r2.Inthiscase, updatingtoamorerecentversionoftheblockingpackagewouldremovetheblock. Itisalsopossiblethattwopackagesthatareyettobeinstalledareblockingeachother.Inthisrarecase,you shouldfindoutwhyyouneedtoinstallboth.Inmostcasesyoucandowithoneofthepackagesalone.Ifnot, pleasefileabugonGentoo'sbugtrackingsystem.

MaskedPackages

CodeListing5.3:Portagewarningaboutmaskedpackages !!aleulstaolaifbosls"hvenmse. !lbidhtcudstsy"otpahaebeakd CodeListing5.4:Portagewarningaboutmaskedpackagesreason !!psiladdtsae !osbecniaer: goebs/nm.._r1(akdb:~8ewr) nmaegoe280pemseyx6kyod lesr/msnos287(akdb:prewr) msnoslesr..mseysackyod sslb/lb...0488(akdb:ewr) yisgic2342000msey*kyod dvui/vd102(akdb:msigkyod etlcs..mseyisnewr) gmsfsuraoraet41(akdb:pcaems) aep/neltunmn5mseyakg.ak sslb/lb..1mseyrfl) yisgic232r1(akdb:poie nti/kp...1(akdb:syeelies() emsye2108mseykpualcnes)

Whenyouwanttoinstallapackagethatisn'tavailableforyoursystem,youwillreceivethismaskingerror.You shouldtryinstallingadifferentapplicationthatisavailableforyoursystemorwaituntilthepackageisputavailable. Thereisalwaysareasonwhyapackageismasked: ~archkeywordmeansthattheapplicationisnottestedsufficientlytobeputinthestablebranch.Waita fewdaysorweeksandtryagain. archkeywordor*keywordmeansthattheapplicationdoesnotworkonyourarchitecture.Ifyoubelieve thepackagedoesworkfileabugatourbugzillawebsite. missingkeywordmeansthattheapplicationhasnotbeentestedonyourarchitectureyet.Askthe architectureportingteamtotestthepackageortestitforthemandreportyourfindingsonourbugzilla website. package.maskmeansthatthepackagehasbeenfoundcorrupt,unstableorworseandhasbeen deliberatelymarkedasdonotuse. profilemeansthatthepackagehasbeenfoundnotsuitableforyourprofile.Theapplicationmightbreak yoursystemifyouinstalleditorisjustnotcompatiblewiththeprofileyouuse. licensemeansthatthepackage'slicenseisnotcompatiblewithyourA C P _ I E S setting.Youmust CETLCNE explicitlypermititslicenseorlicensegroupbysettingitin/ t / a e c n orin ecmk.of / t / o t g / a k g . i e s .RefertoLicensestolearnhowlicenseswork. ecpraepcaelcne

NecessaryUSEFlagChanges
CodeListing5.5:PortagewarningaboutUSEflagchangerequirement TefloigUEcagsaencsaytrce: holwnShnereesropoed #eurdbpethpyakg.,rqieyhpyakgagmn) rqieyaptx/appcae20eurdbappcae(ruet >aptx/elns100ts =petfeig..et

Theerrormessagemightalsobedisplayedasfollows,if a t u m s isn'tset: uonak

CodeListing5.6:PortageerroraboutUSEflagchangerequirement eeg:teeaenbidulihUEfastaifaptx/elnsts]. mrehrroeulsbitwtSlgostsy"petfeig[et" !!Oeoholwnakgsieurdtopeeyueus: !nftefloigpcaesrqieocmltorrqet aptx/elns100(hneUEts) petfeig..CagS:+et (eednyrqiey"pethpyakg."[bid) dpneceurdbaptx/appcae20eul] (eednyrqiey"appcaeagmn] dpneceurdbhpyakg"[ruet)

Suchwarningorerroroccurswhenyouwanttoinstallapackagewhichnotonlydependsonanotherpackage,but alsorequiresthatthatpackageisbuiltwithaparticularUSEflag(orsetofUSEflags).Inthegivenexample,the packagea p t x / e l n s p e t f e i g needstobebuiltwithU E " e t ,butthisUSEflagisnotsetonthesystem. S=ts" Toresolvethis,eitheraddtherequestedUSEflagtoyourglobalUSEflagsin/ t / a e c n ,orsetitforthe ecmk.of specificpackagein/ t / o t g / a k g . s . ecpraepcaeue

MissingDependencies
CodeListing5.7:Portagewarningaboutmissingdependency

eeg:teeaenbidostsy"=yee/c..4. mrehrroeulstaif>ssdvlgc342r" !!Polmwtbidssdvlgc342r !rbeiheulyee/c..2 !!PsilEED*EEDpolm !osbyaDPN/DPNrbe.

Theapplicationyouaretryingtoinstalldependsonanotherpackagethatisnotavailableforyoursystem.Please checkbugzillaiftheissueisknownandifnot,pleasereportit.Unlessyouaremixingbranchesthisshouldnotoccur andisthereforeabug.

AmbiguousEbuildName
CodeListing5.8:Portagewarningaboutambiguousebuildnames [Rslsfrsaceitn] eutoerhky:lse [Apiainon plctosfud:2] *eiyslseakd] dvtno/itn[Mse Ltsesovial:111 aetvrinaalbe..5 Ltsesontle:[NtIsald] aetvrinisaldontle Szffls002k ieoie:1,3B Hmpg:tp/wwtno.e/ oeaeht:/w.iysnt DsrpinaitnfrTnO ecito:RwlseoiyS LcneS ies:BD *eion/itn[Mse mdasudlseakd] Ltsesovial:063 aetvrinaalbe.. Ltsesontle:[NtIsald] aetvrinisaldontle Szffls5B ieoie:89k Hmpg:tp/wwlserjc.r oeaeht:/w.itnpoetog DsrpinuilyradmngmnoNM ecito:AMscpaenaaeetfrGOE LcneP ies:GL2 !!Tesoteulae"itnsabgoslaeseiy !hhrbidnmlse"imiuu.Pespcf !!oeohbvululfebidnmsised !nfteaoeflyqaiideulaenta.

Theapplicationyouwanttoinstallhasanamethatcorrespondswithmorethanonepackage.Youneedtosupply thecategorynameaswell.Portagewillinformyouofpossiblematchestochoosefrom.

CircularDependencies
CodeListing5.9:Portagewarningaboutcirculardependencies !!Erriclrdpnece: !ro:cruaeednis eulern/us1112dpnsobid/aptx/hssrp.53r bid/ntpitcp..5reedneulpetgotcit70.1 eulpetgotcit70.1dpnsobid/ntpitcp..5r bid/aptx/hssrp.53reedneulern/us1112

Two(ormore)packagesyouwanttoinstalldependoneachotherandcanthereforenotbeinstalled.Thisismost likelyabuginthePortagetree.Pleaseresyncafterawhileandtryagain.Youcanalsocheckbugzillaiftheissueis knownandifnot,reportit.

Fetchfailed
CodeListing5.10:Portagewarningaboutfetchfailed !!Fthfieoyisnuss54r,cniun.. !ecaldfrsslb/cre.5otnig. (.) .. !!Smecroswrnonee.laeseaoefrdtis !oeftherreeecutrdPesebvoeal.

Portagewasunabletodownloadthesourcesforthegivenapplicationandwilltrytocontinueinstallingtheother applications(ifapplicable).Thisfailurecanbeduetoamirrorthathasnotsynchronisedcorrectlyorbecausethe ebuildpointstoanincorrectlocation.Theserverwherethesourcesresidecanalsobedownforsomereason. Retryafteronehourtoseeiftheissuestillpersists.

SystemProfileProtection
CodeListing5.11:Portagewarningaboutprofileprotectedpackage !!Tynoumrepcaesnsserfl.'ypsprae !rigtnegakg()iytmpoiessap/otg' !!Tioledmgnoyuytm !hscudbaaigtorsse.

Youhaveaskedtoremoveapackagethatispartofyoursystem'scorepackages.Itislistedinyourprofileas requiredandshouldthereforenotberemovedfromthesystem.

DigestVerificationFailures
Sometimes,whenyouattempttoemergeapackage,itwillfailwiththemessage:
CodeListing5.12:Digestverificationfailure >>ceknbidcekus >hcigeulhcsm !!Dgseiiainfie: !ietvrfctoald

ThisisasignthatsomethingiswrongwiththePortagetreeoften,itisbecauseadevelopermayhavemadea mistakewhencommittingapackagetothetree. Whenthedigestverificationfails,donottrytoredigestthepackageyourself.Runninge u l o a i e t bidfomnfs willnotfixtheproblemitwillalmostcertainlymakeitworse! Instead,waitanhourortwoforthetreetosettledown.It'slikelythattheerrorwasnoticedrightaway,butitcan takealittletimeforthefixtotrickledownthePortagetree.Whileyou'rewaiting,checkBugzillaandseeifanyone hasreportedtheproblemyet.Ifnot,goaheadandfileabugforthebrokenpackage. Onceyouseethatthebughasbeenfixed,youmaywanttoresynctopickupthefixeddigest.

Important:Thisdoesnotmeanthatyoucanresyncyourtreemultipletimes!Asstatedinthersyncpolicy(whenyourune e g mre s n ),userswhosynctoooftenwillbebanned!Infact,it'sbettertojustwaituntilyournextscheduledsync,sothatyoudon't yc overloadthersyncservers.

2.USEflags
6.a.WhatareUSEflags? TheideasbehindUSEflags
WhenyouareinstallingGentoo(oranyotherdistribution,orevenoperatingsystemforthatmatter)youmake choicesdependingontheenvironmentyouareworkingwith.Asetupforaserverdiffersfromasetupfora workstation.Agamingworkstationdiffersfroma3Drenderingworkstation. Thisisnotonlytrueforchoosingwhatpackagesyouwanttoinstall,butalsowhatfeaturesacertainpackageshould support.Ifyoudon'tneedOpenGL,whywouldyoubotherinstallingOpenGLandbuildOpenGLsupportinmostof yourpackages?Ifyoudon'twanttouseKDE,whywouldyoubothercompilingpackageswithKDEsupportifthose packagesworkflawlesslywithout? Tohelpusersindecidingwhattoinstall/activateandwhatnot,wewantedtheusertospecifyhis/herenvironmentin aneasyway.ThisforcestheuserintodecidingwhattheyreallywantandeasestheprocessforPortage,our packagemanagementsystem,tomakeusefuldecisions.

DefinitionofaUSEflag
EntertheUSEflags.Suchaflagisakeywordthatembodiessupportanddependencyinformationforacertain concept.IfyoudefineacertainUSEflag,Portagewillknowthatyouwantsupportforthechosenkeyword.Of coursethisalsoaltersthedependencyinformationforapackage. Letustakealookataspecificexample:thek e d keyword.IfyoudonothavethiskeywordinyourU E S variable,all packagesthathaveoptionalKDEsupportwillbecompiledwithoutKDEsupport.Allpackagesthathaveanoptional KDEdependencywillbeinstalledwithoutinstallingtheKDElibraries(asdependency).Ifyouhavedefinedthek e d

keyword,thenthosepackageswillbecompiledwithKDEsupport,andtheKDElibrarieswillbeinstalledas dependency. Bycorrectlydefiningthekeywordsyouwillreceiveasystemtailoredspecificallytoyourneeds.

WhatUSEflagsexist?
TherearetwotypesofUSEflags:globalandlocalUSEflags. AglobalUSEflagisusedbyseveralpackages,systemwide.ThisiswhatmostpeopleseeasUSEflags. AlocalUSEflagisusedbyasinglepackagetomakepackagespecificdecisions. AlistofavailableglobalUSEflagscanbefoundonlineorlocallyin/ s / o t g / r f l s u e d s . urpraepoie/s.ec AlistofavailablelocalUSEflagscanbefoundlocallyin/ s / o t g / r f l s u e l c l d s . urpraepoie/s.oa.ec

2.b.UsingUSEflags DeclarepermanentUSEflags
InthehopeyouareconvincedoftheimportanceofUSEflagswewillnowinformyouhowtodeclareUSEflags. Aspreviouslymentioned,allUSEflagsaredeclaredinsidetheU E S variable.Tomakeiteasyforuserstosearch andpickUSEflags,wealreadyprovideadefaultUSEsetting.ThissettingisacollectionofUSEflagswethinkare commonlyusedbytheGentoousers.Thisdefaultsettingisdeclaredinthem k . e a l s a e d f u t filespartofyour profile. Theprofileyoursystemlistenstoispointedtobythe/ t / a e p o i e e c m k . r f l symlink.Eachprofileworksontopof another,largerprofile,theendresultisthereforethesumofallprofiles.Thetopprofileistheb s profile ae (/ s / o t g / r f l s b s ). urpraepoie/ae Letustakealookatthisdefaultsettingforthe10.0profile:
CodeListing2.1:Cumulativemake.defaultsUSEvariableforthe10.0profile (hseapeihuftestignbs,dfutlnx Tixmlstesmohetnsiaeeal/iu, eal/iu/8neal/iu/8/00) dfutlnxx6addfutlnxx61./ UE"5aciasrnigciocrdutvvrebsnoeei S=a2acaplabadnardbsdsddddmosecdxf fmfrfxfaiptapglmdplboiymdmkonp aieolcgfgmgkhljecslaintfaimdmgm3 m4megpnlpnopfpgpdtspotq4slsel ppgogoegagdnpsq3uprtdpl satpntfctoviftutpobsuioeubXxbx6mv truoiiainsgtfreyevrincdsc24xlx xi" vd

Asyoucansee,thisvariablealreadycontainsquitealotofkeywords.Donotalteranym k . e a l s a e d f u t fileto tailortheU E S variabletoyourneeds:changesinthisfilewillbeundonewhenyouupdatePortage! Tochangethisdefaultsetting,youneedtoaddorremovekeywordstotheU E S variable.Thisisdonegloballyby definingtheU E S variablein/ t / a e c n .InthisvariableyouaddtheextraUSEflagsyourequire,or ecmk.of removetheUSEflagsyoudon'twant.Thislatterisdonebyprefixingthekeywordwiththeminussign(""). Forinstance,toremovesupportforKDEandQTbutaddsupportforldap,thefollowingU E S canbedefinedin /t/aecn: ecmk.of
CodeListing2.10:AnexampleUSEsettingin/etc/make.conf UE"ketdp S=dq4la"

DeclaringUSEflagsforindividualpackages
SometimesyouwanttodeclareacertainUSEflagforone(oracouple)ofapplicationsbutnotsystemwide.To accomplishthis,youwillneedtocreatethe/ t / o t g directory(ifitdoesn'texistyet)andedit ecprae / t / o t g / a k g . s .Thisisusuallyasinglefile,butcanalsobeadirectoryseem n p r a e ecpraepcaeue a o t g for moreinformation.Thefollowingexamplesassumep c a e u e a k g . s isasinglefile.

Forinstance,ifyoudon'twantb r d supportgloballybutyoudowantitform s l ekb y q ,youwouldadd:

CodeListing2.3:/etc/portage/package.useexample dvd/yqekb ebmslbrd

YoucanofcoursealsoexplicitlydisableUSEflagsforacertainapplication.Forinstance,ifyoudon'twantj v aa supportinPHP:
CodeListing2.4:/etc/portage/package.use2ndexample dvppppaa eh/hjv

DeclaretemporaryUSEflags
SometimesyouwanttosetacertainUSEsettingonlyonce.Insteadofediting/ t / a e c n twice(todoand ecmk.of undotheUSEchanges)youcanjustdeclaretheUSEvariableasenvironmentvariable.Rememberthat,whenyou reemergeorupdatethisapplication(eitherexplicitlyoraspartofasystemupdate)yourchangeswillbelost! AsanexamplewewilltemporarilyremovejavafromtheUSEsettingduringtheinstallationofseamonkey.
CodeListing2.5:UsingUSEasenvironmentvariable #UE"jv"eegemne S=aamresaoky

Precedence
OfcoursethereisacertainprecedenceonwhatsettinghaspriorityovertheUSEsetting.Youdon'twanttodeclare UE"jv" S = a a onlytoseethatj v isstillusedduetoasettingthathasahigherpriority.Theprecedenceforthe aa USEsettingis,orderedbypriority(firsthaslowestpriority): 1. DefaultUSEsettingdeclaredinthem k . e a l s a e d f u t filespartofyourprofile 2. UserdefinedUSEsettingin/ t / a e c n ecmk.of 3. UserdefinedUSEsettingin/ t / o t g / a k g . s ecpraepcaeue 4. UserdefinedUSEsettingasenvironmentvariable ToviewthefinalU E S settingasseenbyPortage,rune e g n o m r e i f .Thiswilllistallrelevantvariables (includingtheU E S variable)withthecontentusedbyPortage.
CodeListing2.6:Runningemergeinfo #eegno mreif

AdaptingyourEntireSystemtoNewUSEFlags
IfyouhavealteredyourUSEflagsandyouwishtoupdateyourentiresystemtousethenewUSEflags,use e e g 's n w s option: mre eue
CodeListing2.7:Rebuildingyourentiresystem #eegpaedeeuewrd mreudtepnwsol

Next,runPortage'sdepcleantoremovetheconditionaldependenciesthatwereemergedonyour"old"systembut thathavebeenobsoletedbythenewUSEflags.
Warning:Runninge e g e c e n m r e d p l a isadangerousoperationandshouldbehandledwithcare.Doublechecktheprovided listof"obsoleted"packagestomakesureitdoesn'tremovepackagesyouneed.Inthefollowingexampleweaddthe switchto p havedepcleanonlylistthepackageswithoutremovingthem. CodeListing2.8:Removingobsoletedpackages #eegpdpla mreecen

Whendepcleanhasfinished,runr v e e u l torebuildtheapplicationsthataredynamicallylinkedagainst edprbid

sharedobjectsprovidedbypossiblyremovedpackages.r v e e u l ispartoftheg n o l i package edprbid etokt don'tforgettoemergeitfirst.

CodeListing2.9:Runningrevdeprebuild #rveeul edprbid

Whenallthisisaccomplished,yoursystemisusingthenewUSEflagsettings.

2.c.PackagespecificUSEflags ViewingavailableUSEflags
Letustaketheexampleofs a o k y e m n e :whatUSEflagsdoesitlistento?Tofindout,weusee e g withthe mre peed r t n and v r o e e b s options:
CodeListing3.1:ViewingtheusedUSEflags #eegrtnebsemne mrepeedvroesaoky TeeaetepcaehtIwudmrenodr hsrhakgstaoleg,ire: Cluaigdpnece.dn! acltneednis..oe [bidR]wwcin/emne..UE"rpnmaaeuiv eulwletsaoky107S=cytgoejvdbgp6 dpoclnamzeeomzoopsmzormzoalonpno lamzaedrodvlponcmoeoniconmimzoag onraigotrsieaapitB mzoomnpsgexnrmxrn"0k

e e g isn'ttheonlytoolforthisjob.Infact,wehaveatooldedicatedtopackageinformationcallede u r mre qey whichresidesintheg n o l i package.First,installg n o l i : etokt etokt

CodeListing3.2:Installinggentoolkit #eegetokt mregnoli

Nowrune u r withtheu e argumenttoviewtheUSEflagsofacertainpackage.Forinstance,forthe qey ss g u e i package: nmrc

CodeListing3.3:UsingequerytoviewusedUSEflags #euroooss=nmrc163 qeynclrueguei..a [Sacigfrpcaeacig=nmrc163. erhnoakgsmthnguei....] [Cluoe:stust] oorCdene [Lgnetclm()UEfasfoaecn] eed:LfounUSlgrmmk.of [ihoun()UEfaspcaeantleih] :RgtclmISlgakgswsisaldwt [FudteeUEvralsfrapofc/nmrc163] onhsSaibeopfieguei.. UI eu:Ealxreuoeah,lksetnxrupt dbgnbeetadbgcdptsieasrsadetaotu. Ioatteennflbctaee fyuwnogtmaiguakrcsse ht:/w.etoogpo/nq/akrcsxl. tp/wwgno.r/rje/abctae.m nm:AdNMupr ++goedsGOEspot yhn:Adupr/idnsfrtePtoagae ++ptodsspotbnigohyhnlnug ttc:!doehsdrnotta!assbnreob sai!ontsttiuigbosrp!Cueiaiste saialikdisedoyaial ttclylnentafdnmcly

3.PortageFeatures
3.a.PortageFeatures
PortagehasseveraladditionalfeaturesthatmakesyourGentooexperienceevenbetter.Manyofthesefeaturesrely oncertainsoftwaretoolsthatimproveperformance,reliability,security,... ToenableordisablecertainPortagefeaturesyouneedtoedit/ t / a e c n 'sF A U E variablewhich ecmk.of ETRS containsthevariousfeaturekeywords,separatedbywhitespace.Inseveralcasesyouwillalsoneedtoinstallthe additionaltoolonwhichthefeaturerelies.

NotallfeaturesthatPortagesupportsarelistedhere.Forafulloverview,pleaseconsultthem k . o f a e c n man page:

CodeListing1.1:Consultingthemake.confmanpage $mnmk.of aaecn

TofindoutwhatFEATURESaredefaultset,rune e g n o m r e i f andsearchfortheFEATURESvariableorgrep itout:

CodeListing1.2:FindingouttheFEATURESthatarealreadyset $eegno|geETRS mreifrpFAUE

7.c.DistributedCompiling Usingdistcc
d s c isaprogramtodistributecompilationsacrossseveral,notnecessarilyidentical,machinesonanetwork. itc Thed s c clientsendsallnecessaryinformationtotheavailabledistccservers(runningd s c d itc i t c )sotheycan compilepiecesofsourcecodefortheclient.Thenetresultisafastercompilationtime. Youcanfindmoreinformationaboutd s c (andhowtohaveitworkwithGentoo)inourGentooDistcc itc Documentation.

Installingdistcc
Distccshipswithagraphicalmonitortomonitortasksthatyourcomputerissendingawayforcompilation.Ifyouuse Gnomethenput'gnome'inyourUSEvariable.However,ifyoudon'tuseGnomeandwouldstillliketohavethe monitorthenyoushouldput'gtk'inyourUSEvariable.
CodeListing2.1:Installingdistcc #eegitc mredsc

ActivatingPortageSupport
Addd s c totheFEATURESvariableinside/ t / a e c n .Next,edittheMAKEOPTSvariabletoyour itc ecmk.of liking.Aknownguidelineistofillin"jX"withXthenumberofCPUsthatrund s c d i t c (includingthecurrenthost) plusone,butyoumighthavebetterresultswithothernumbers. Nowrund s c o f g i t c c n i andenterthelistofavailabledistccservers.Forasimpleexampleweassumethatthe availableDistCCserversare192.168.1.102(thecurrenthost),192.168.1.103and192.168.1.104(two"remote" hosts):
CodeListing2.2:Configuringdistcctousethreeavailabledistccservers #dscofgsthss"9.6..09.6..09.6..0" itccnieot121811212181131218114

Don'tforgettorunthed s c d i t c daemonaswell:
CodeListing2.3:Startingthedistccddaemons #rpaeaddscddfut cudtditceal #/t/ntddscdsat ecii./itctr

3.c.CachingCompilation Aboutccache
c a h isafastcompilercache.Whenyoucompileaprogram,itwillcacheintermediateresultssothat,whenever cce yourecompilethesameprogram,thecompilationtimeisgreatlyreduced.Thefirsttimeyourunccache,itwillbe muchslowerthananormalcompilation.Subsequentrecompilesshouldbefaster.ccacheisonlyhelpfulifyouwill

berecompilingthesameapplicationmanytimesthusit'smostlyonlyusefulforsoftwaredevelopers. Ifyouareinterestedintheinsandoutsofccache,pleasevisittheccachehomepage.
Warning:c a h isknowntocausenumerouscompilationfailures.Sometimesccachewillretainstalecodeobjectsorcorrupted cce files,whichcanleadtopackagesthatcannotbeemerged.Ifthishappens(ifyoureceiveerrorslike"Filenotrecognized:File truncated"),tryrecompilingtheapplicationwithccachedisabled(F A U E = c c e in/ t / a e c n )beforereporting ETRS"cah" ecmk.of abug.Unlessyouaredoingdevelopmentwork,donotenableccache.

Installingccache
Toinstallc a h ,rune e g c c e cce mrecah:
CodeListing3.1:Installingccache #eegcce mrecah

ActivatingPortageSupport
Open/ t / a e c n andaddc a h totheFEATURESvariable.Next,addanewvariablecalled ecmk.of cce CCACHE_SIZEandsetitto"2G":
CodeListing3.2:EditingCCACHE_SIZEin/etc/make.conf CAH_IE"G CCESZ=2"

Tocheckifccachefunctions,askccachetoprovideyouwithitsstatistics.BecausePortageusesadifferentccache homedirectory,youneedtosettheC A H _ I variableaswell: CCEDR

CodeListing3.3:Viewingccachestatistics #CAH_I=/a/m/ccecce CCEDR"vrtpcah"cahs

The/ a / m / c c e v r t p c a h locationisPortage'defaultccachehomedirectoryifyouwanttoalterthissettingyoucan settheC A H _ I variablein/ t / a e c n . CCEDR ecmk.of However,ifyouwouldrunc a h ,itwouldusethedefaultlocationof$ H M } . c c e cce { O E / c a h ,whichiswhyyou neededtosettheC A H _ I variablewhenaskingforthe(Portage)ccachestatistics. CCEDR

UsingccachefornonPortageCCompiling
IfyouwouldliketouseccachefornonPortagecompilations,add/ s / i / c c e b n u r l b c a h / i tothebeginningof yourPATHvariable(before/ s / i ).Thiscanbeaccomplishedbyediting. a h p o i e urbn b s _ r f l inyouruser's homedirectory.Using. a h p o i e b s _ r f l isonewaytodefinePATHvariables.
CodeListing3.4:Editing.bash_profile PT=/s/i/ccebn/p/i:{AH" AH"urlbcah/i:otbn$PT}

3.d.BinaryPackageSupport CreatingPrebuiltPackages
Portagesupportstheinstallationofprebuiltpackages.EventhoughGentoodoesnotprovideprebuiltpackagesby itself(exceptfortheGRPsnapshots)Portagecanbemadefullyawareofprebuiltpackages. Tocreateaprebuiltpackageyoucanuseq i k k ifthepackageisalreadyinstalledonyoursystem,ore e g ucpg mre withthe b i d k or b i d k o l options. ulpg ulpgny IfyouwantPortagetocreateprebuiltpackagesofeverysinglepackageyouinstall,addb i d k tothe ulpg FEATURESvariable. Moreextendedsupportforcreatingprebuiltpackagesetscanbeobtainedwithc t l s .Formoreinformationon aayt

catalystpleasereadtheCatalystFrequentlyAskedQuestions.

InstallingPrebuiltPackages
AlthoughGentoodoesn'tprovideone,youcancreateacentralrepositorywhereyoustoreprebuiltpackages.Ifyou wanttousethisrepository,youneedtomakePortageawareofitbyhavingthePORTAGE_BINHOSTvariable pointtoit.Forinstance,iftheprebuiltpackagesareonftp://buildhost/gentoo:
CodeListing4.1:SettingPORTAGE_BINHOSTin/etc/make.conf PRAEBNOT"t:/ulhs/eto OTG_IHS=fp/bidotgno"

Whenyouwanttoinstallaprebuiltpackage,addthe g t i p g e b n k optiontotheemergecommandalongsideof the u e k option.Theformertellsemergetodownloadtheprebuiltpackagefromthepreviouslydefinedserver spg whilethelatterasksemergetotrytoinstalltheprebuiltpackagefirstbeforefetchingthesourcesandcompilingit. Forinstance,toinstallg u e i withprebuiltpackages: nmrc

CodeListing4.2:Installingthegnumericprebuiltpackage #eegspggtipgguei mreuekebnknmrc

Moreinformationaboutemerge'sprebuiltpackageoptionscanbefoundintheemergemanpage:
CodeListing4.3:Readingtheemergemanpage $mneeg amre

3.e.FetchingFiles Parallelfetch
Whenyouareemergingaseriesofpackages,Portagecanfetchthesourcefilesforthenextpackageinthelist evenwhileitiscompilinganotherpackage,thusshorteningcompiletimes.Tomakeuseofthiscapability,add "parallelfetch"toyourFEATURES.Notethatthisisonbydefault,soyoushouldn'tneedtospecificallyenableit.

Userfetch
WhenPortageisrunasroot,FEATURES="userfetch"willallowPortagetodroprootprivilegeswhilefetching packagesources.Thisisasmallsecurityimprovement.

3.f.PullingValidatedPortageTreeSnapshots
Asanadministrator,youcanopttoonlyupdateyourlocalPortagetreewithacryptographicallyvalidatedPortage treesnapshotasreleasedbytheGentooinfrastructure.Thisensuresthatnoroguersyncmirrorisaddingunwanted codeorpackagesinthetreeyouaredownloading. ToconfigurePortage,firstcreateatruststoreinwhichyoudownloadandacceptthekeysoftheGentoo InfrastructureresponsibleforsigningthePortagetreesnapshots.Ofcourse,ifyouwantto,youcanvalidatethis GPGkeyaspertheproperguidelines(likecheckingthekeyfingerprint).YoucanfindthelistofGPGkeysusedby thereleaseengineeringteamontheirprojectpage.
CodeListing6.1:CreatingatruststoreforPortage #mdrecpraegg kip/t/otg/p #cmd00ecpraegg ho70/t/otg/p (.usiuetekyihtoemnindoheesniernie.. ..Sbtttheswthsetoenterlaeegneigst.) #gghmdr/t/otg/pesreuky.g.eevkyx3C5409DB6 poeiecpraeggkyevrsbesppntrces0297Cx68FD #gghmdr/t/otg/pdtky0297Crs poeiecpraeggeiex3C54tut #gghmdr/t/otg/pdtky09DB6rs poeiecpraeggeiex68FDtut

Next,edit/ t / a e c n andenablesupportforvalidatingthesignedPortagetreesnapshots(using ecmk.of FAUE=wbsnp" E T R S " e r y c g g )anddisablingupdatingthePortagetreeusingtheregulare e g y c mresn

method.
CodeListing6.2:UpdatingPortageforsignedtreevalidation FAUE=wbsnp" ETRS"erycgg PRAEGGDR"ecpraegg OTG_P_I=/t/otg/p" SN=" YC"

That'sit.Nexttimeyourune e g e r y c m r e w b s n ,onlythesnapshotswithavalidsignaturewillbeexpandedon yourfilesystem.

4.Initscripts
4.a.Runlevels BootingyourSystem
Whenyoubootyoursystem,youwillnoticelotsoftextfloatingby.Ifyoupaycloseattention,youwillnoticethis textisthesameeverytimeyourebootyoursystem.Thesequenceofalltheseactionsiscalledthebootsequence andis(moreorless)staticallydefined. First,yourbootloaderwillloadthekernelimageyouhavedefinedinthebootloaderconfigurationintomemory afterwhichittellstheCPUtorunthekernel.Whenthekernelisloadedandrun,itinitializesallkernelspecific structuresandtasksandstartsthei i process. nt Thisprocessthenmakessurethatallfilesystems(definedin/ t / s a )aremountedandreadytobeused. ecftb Thenitexecutesseveralscriptslocatedin/ t / n t d e c i i . ,whichwillstarttheservicesyouneedinordertohavea successfullybootedsystem. Finally,whenallscriptsareexecuted,i i activatestheterminals(inmostcasesjustthevirtualconsoleswhich nt arehiddenbeneathA t F ,A t F ,etc.)attachingaspecialprocesscalleda e t toit.Thisprocesswillthen l1 l2 gty makesureyouareabletologonthroughtheseterminalsbyrunningl g n oi.

InitScripts
Nowi i doesn'tjustexecutethescriptsin/ t / n t d nt e c i i . randomly.Evenmore,itdoesn'trunallscriptsin /t/ntd e c i i . ,onlythescriptsitistoldtoexecute.Itdecideswhichscriptstoexecutebylookinginto /t/ulvl. ecrnees First,i i runsallscriptsfrom/ t / n t d nt e c i i . thathavesymboliclinksinside/ t / u l v l / o t e c r n e e s b o .Usually, itwillstartthescriptsinalphabeticalorder,butsomescriptshavedependencyinformationinthem,tellingthe systemthatanotherscriptmustberunbeforetheycanbestarted. Whenall/ t / u l v l / o t e c r n e e s b o referencedscriptsareexecuted,i i continueswithrunningthescriptsthat nt haveasymboliclinktothemin/ t / u l v l / e a l .Again,itwillusethealphabeticalordertodecide ecrneesdfut whatscripttorunfirst,unlessascripthasdependencyinformationinit,inwhichcasetheorderischangedto provideavalidstartupsequence.

HowInitWorks
Ofcoursei i doesn'tdecideallthatbyitself.Itneedsaconfigurationfilethatspecifieswhatactionsneedtobe nt taken.Thisconfigurationfileis/ t / n t a . eciitb Ifyourememberthebootsequencewehavejustdescribed,youwillrememberthati i 'sfirstactionistomount nt allfilesystems.Thisisdefinedinthefollowinglinefrom/ t / n t a : eciitb
CodeListing1.1:Thesysteminitialisationlinein/etc/inittab s:ssnt/bnryii i:yii:si/cssnt

Thislinetellsi i thatitmustrun/ b n r y i i toinitializethesystem.The/ b n r scripttakescare nt si/cssnt si/c oftheinitialisation,soyoumightsaythati i doesn'tdomuchitdelegatesthetaskofinitialisingthesystemto nt

anotherprocess. Second,i i executedallscriptsthathadsymboliclinksin/ t / u l v l / o t nt e c r n e e s b o .Thisisdefinedinthe followingline:

CodeListing1.2:Thesysteminitialisation,continued r:bowi:si/cbo c:otat/bnrot

Againther scriptperformsthenecessarytasks.Notethattheoptiongiventor (boot)isthesameasthe c c subdirectoryof/ t / u l v l thatisused. ecrnees Nowi i checksitsconfigurationfiletoseewhatrunlevelitshouldrun.Todecidethis,itreadsthefollowingline nt from/ t / n t a : eciitb
CodeListing1.3:Theinitdefaultline i::nteal: d3iidfut

Inthiscase(whichthemajorityofGentoouserswilluse),therunlevelidis3.Usingthisinformation,i i checks nt whatitmustruntostartrunlevel3:

CodeListing1.4:Therunleveldefinitions l::at/bnrhton 00wi:si/csudw l:1wi:si/csnl 1S:at/bnrige l::at/bnroewr 22wi:si/cnntok l::at/bnreal 33wi:si/cdfut l::at/bnreal 44wi:si/cdfut l::at/bnreal 55wi:si/cdfut l::at/bnreot 66wi:si/crbo

Thelinethatdefineslevel3,again,usesther scripttostarttheservices(nowwithargumentdefault).Againnote c thattheargumentofr isthesameasthesubdirectoryfrom/ t / u l v l . c ecrnees Whenr hasfinished,i i decideswhatvirtualconsolesitshouldactivateandwhatcommandsneedtoberunat c nt eachconsole:

CodeListing1.5:Thevirtualconsolesdefinition c:24:epw:si/gty340tyiu 1135rsan/bnaet80t1lnx c:24:epw:si/gty340tyiu 2135rsan/bnaet80t2lnx c:24:epw:si/gty340tyiu 3135rsan/bnaet80t3lnx c:24:epw:si/gty340tyiu 4135rsan/bnaet80t4lnx c:24:epw:si/gty340tyiu 5135rsan/bnaet80t5lnx c:24:epw:si/gty340tyiu 6135rsan/bnaet80t6lnx

Whatisarunlevel?
Youhaveseenthati i usesanumberingschemetodecidewhatrunlevelitshouldactivate.Arunlevelisastate nt inwhichyoursystemisrunningandcontainsacollectionofscripts(runlevelscriptsorinitscripts)thatmustbe executedwhenyouenterorleavearunlevel. InGentoo,therearesevenrunlevelsdefined:threeinternalrunlevels,andfouruserdefinedrunlevels.Theinternal runlevelsarecalledsysinit,shutdownandrebootanddoexactlywhattheirnamesimply:initializethesystem, poweringoffthesystemandrebootingthesystem. Theuserdefinedrunlevelsarethosewithanaccompanying/ t / u l v l subdirectory:b o ,d f u t ecrnees ot eal, nntok o e w r ands n l .Theb o runlevelstartsallsystemnecessaryserviceswhichallotherrunlevelsuse. ige ot Theremainingthreerunlevelsdifferinwhatservicestheystart:d f u t e a l isusedfordaytodayoperations, nntok o e w r isusedincasenonetworkconnectivityisrequired,ands n l isusedwhenyouneedtofixthe ige system.

WorkingwiththeInitScripts

Thescriptsthatther processstartsarecalledinitscripts.Eachscriptin/ t / n t d c e c i i . canbeexecutedwiththe argumentsstart,stop,restart,pause,zap,status,ineed,iuse,needsme,usesmeorbroken. Tostart,stoporrestartaservice(andalldependingservices),s a t t p t r ,s o andr s a t e t r shouldbeused:

CodeListing1.6:StartingPostfix #/t/ntdpsfxsat ecii./otitr Note:Onlytheservicesthatneedthegivenservicearestoppedorrestarted.Theotherdependingservices(thosethatusethe servicebutdon'tneedit)areleftuntouched.

Ifyouwanttostopaservice,butnottheservicesthatdependonit,youcanusethep u e a s argument:
CodeListing1.7:StoppingPostfixbutkeepthedependingservicesrunning #/t/ntdpsfxpue ecii./otias

Ifyouwanttoseewhatstatusaservicehas(started,stopped,paused,...)youcanusethes a u argument: tts

CodeListing1.8:Statusinformationforpostfix #/t/ntdpsfxsau ecii./otitts

Ifthestatusinformationtellsyouthattheserviceisrunning,butyouknowthatitisnot,thenyoucanresetthe statusinformationto"stopped"withthez p a argument:

CodeListing1.9:Resettingstatusinformationforpostfix #/t/ntdpsfxzp ecii./otia

Toalsoaskwhatdependenciestheservicehas,youcanusei s ori e d ue n e .Withi e d n e youcanseetheservices thatarereallynecessaryforthecorrectfunctioningoftheservice.i s ontheotherhandshowstheservicesthat ue canbeusedbytheservice,butarenotnecessaryforthecorrectfunctioning.

CodeListing1.10:RequestingalistofallnecessaryservicesonwhichPostfixdepends #/t/ntdpsfxied ecii./otine

Similarly,youcanaskwhatservicesrequiretheservice(n e s e e d m )orcanuseit(u e m ): sse

CodeListing1.11:RequestingalistofallservicesthatrequirePostfix #/t/ntdpsfxnese ecii./otiedm

Finally,youcanaskwhatdependenciestheservicerequiresthataremissing:
CodeListing1.12:RequestingalistofmissingdependenciesforPostfix #/t/ntdpsfxboe ecii./otirkn

4.b.Workingwithrcupdate Whatisrcupdate?
Gentoo'sinitsystemusesadependencytreetodecidewhatserviceneedstobestartedfirst.Asthisisatedious taskthatwewouldn'twantouruserstohavetodomanually,wehavecreatedtoolsthateasetheadministrationof therunlevelsandinitscripts. Withr p a e c u d t youcanaddandremoveinitscriptstoarunlevel.Ther p a e c u d t toolwillthenautomatically askthed p c n s scripttorebuildthedependencytree. esa.h

AddingandRemovingServices
Youhavealreadyaddedinitscriptstothe"default"runlevelduringtheinstallationofGentoo.Atthattimeyoumight

nothavehadacluewhatthe"default"isfor,butnowyoushould.Ther p a e c u d t scriptrequiresasecond argumentthatdefinestheaction:add,delorshow. Toaddorremoveaninitscript,justgiver p a e c u d t thea d d ord l e argument,followedbytheinitscriptandthe runlevel.Forinstance:

CodeListing2.1:RemovingPostfixfromthedefaultrunlevel #rpaedlpsfxdfut cudteotieal

Ther p a e h w c u d t v s o commandwillshowalltheavailableinitscriptsandlistatwhichrunlevelstheywill execute:

CodeListing2.2:Receivinginitscriptinformation #rpaehw cudtvso

Youcanalsorunr p a e s o (without )tojustviewenabledinitscriptsandtheirrunlevels. cudthw v

4.c.ConfiguringServices WhytheNeedforExtraConfiguration?
Initscriptscanbequitecomplex.Itisthereforenotreallydesirabletohavetheusersedittheinitscriptdirectly,asit wouldmakeitmoreerrorprone.Itishoweverimportanttobeabletoconfiguresuchaservice.Forinstance,you mightwanttogivemoreoptionstotheserviceitself. Asecondreasontohavethisconfigurationoutsidetheinitscriptistobeabletoupdatetheinitscriptswithoutthe fearthatyourconfigurationchangeswillbeundone.

The/etc/conf.dDirectory
Gentooprovidesaneasywaytoconfiguresuchaservice:everyinitscriptthatcanbeconfiguredhasafilein /t/ofd e c c n . .Forinstance,theapache2initscript(called/ t / n t d a a h 2 e c i i . / p c e )hasaconfigurationfile called/ t / o f d a a h 2 e c c n . / p c e ,whichcancontaintheoptionsyouwanttogivetotheApache2serverwhenitis started:
CodeListing3.1:Variabledefinedin/etc/conf.d/apache2 AAH2OT=H5 PCE_PS"DPP"

Suchaconfigurationfilecontainsvariablesandvariablesalone(justlike/ t / a e c n ),makingitveryeasyto ecmk.of configureservices.Italsoallowsustoprovidemoreinformationaboutthevariables(ascomments).

4.d.WritingInitScripts DoIHaveTo?
No,writinganinitscriptisusuallynotnecessaryasGentooprovidesreadytouseinitscriptsforallprovided services.However,youmighthaveinstalledaservicewithoutusingPortage,inwhichcaseyouwillmostlikelyhave tocreateaninitscript. Donotusetheinitscriptprovidedbytheserviceifitisn'texplicitlywrittenforGentoo:Gentoo'sinitscriptsarenot compatiblewiththeinitscriptsusedbyotherdistributions!

Layout
Thebasiclayoutofaninitscriptisshownbelow.
CodeListing4.1:Basiclayoutofaninitscript #/bnrncit !si/usrp dpn( eed){

(eednyifrain Dpnecnomto) } sat){ tr( (omnsncsayttrhevc) Cmadeesrosattesrie } so( tp){ (omnsncsayttptesrie Cmadeesrosohevc) }

Anyinitscriptrequiresthes a t ) t r ( functiontobedefined.Allothersectionsareoptional.

Dependencies
Therearetwodependencyalikesettingsyoucandefinethatinfluencethestartuporsequencingofinitscripts:u e s andn e .Nexttothesetwo,therearealsotwoorderinfluencingmethodscalledb f r anda t r ed eoe f e .Theselast twoarenodependenciespersetheydonotmaketheoriginalinitscriptfailiftheselectedoneisn'tscheduledto start(orfailstostart). Theu e s settingsinformstheinitsystemthatthisscriptusesfunctionalityofferedbytheselectedscript,but doesnotdirectlydependonit.Agoodexamplewouldbeu e l g e oru e d s sogr s n .Ifthoseservicesare available,theywillbeputingooduse,butifyoudonothavealoggerorDNSservertheserviceswillstill work.Iftheservicesexist,thentheyarestartedbeforethescriptthatu e s 'sthem. Then e settingisaharddependency.Itmeansthatthescriptthatisn e 'inganotherscriptwillnotstart ed ed beforetheotherscriptislaunchedsuccessfully.Also,ifthatotherscriptisrestarted,thenthisonewillbe restartedaswell. Whenusingb f r ,thenthegivenscriptislaunchedbeforetheselectedoneiftheselectedoneispartof eoe theinitlevel.Soaninitscriptx m d thatdefinesb f r l a o n willstartbeforethea s s u d eoeassud laon script,butonlyifa s s u d l a o n isscheduledtostartaswellinthesameinitlevel.Ifa s s u d l a o n isnot scheduledtostarttoo,thenthisparticularsettinghasnoeffectandx m d willbestartedwhentheinitsystem deemsitmostappropriate. Similarly,a t r f e informstheinitsystemthatthegivenscriptshouldbelaunchedaftertheselectedoneif theselectedoneispartoftheinitlevel.Ifnot,thenthesettinghasnoeffectandthescriptwillbelaunched bytheinitsystemwhenitdeemsitmostappropriate. Itshouldbeclearfromtheabovethatn e istheonly"true"dependencysettingasitaffectsifthescriptwillbe ed startedornot.Alltheothersaremerelypointerstowardstheinitsystemtoclarifyinwhichorderscriptscanbe(or shouldbe)launched. Now,ifyoulookatmanyofGentoo'savailableinitscripts,youwillnoticethatsomehavedependenciesonthings thatarenoinitscripts.These"things"wecallvirtuals. Avirtualdependencyisadependencythataserviceprovides,butthatisnotprovidedsolelybythatservice.Your initscriptcandependonasystemlogger,buttherearemanysystemloggersavailable(metalogd,syslogng, sysklogd,...).Asyoucannotn e everysingleoneofthem(nosensiblesystemhasallthesesystemloggers ed installedandrunning)wemadesurethatalltheseservicesp o i e r v d avirtualdependency. Letustakealookatthedependencyinformationforthepostfixservice.
CodeListing4.2:DependencyinformationforPostfix dpn( eed){ nee ednt uelgen sogrds poiema rvdt }

Asyoucansee,thepostfixservice: requiresthe(virtual)n t e dependency(whichisprovidedby,forinstance,/ t / n t d n t e h ) ecii./e.t0

usesthe(virtual)l g e dependency(whichisprovidedby,forinstance,/ t / n t d s s o g ogr ecii./ylgn) usesthe(virtual)d s n dependency(whichisprovidedby,forinstance,/ t / n t d n m d ecii./ae) providesthe(virtual)m a t dependency(whichiscommonforallmailservers)

ControllingtheOrder
Aswedescribedintheprevioussection,youcantelltheinitsystemwhatorderitshoulduseforstarting(or stopping)scripts.Thisorderingishandledboththroughthedependencysettingsu e s andn e ,butalsothrough ed theordersettingsb f r anda t r eoe f e .Aswehavedescribedtheseearlieralready,let'stakealookatthePortmap serviceasanexampleofsuchinitscript.
CodeListing4.3:Thedepend()functioninthePortmapservice dpn( eed){ nee ednt bfrnt eoeied bfried eoexnt }

Youcanalsousethe"*"globtocatchallservicesinthesamerunlevel,althoughthisisn'tadvisable.
CodeListing4.4:Runninganinitscriptasfirstscriptintherunlevel dpn( eed){ bfr eoe* }

Ifyourservicemustwritetolocaldisks,itshouldneedl c l o n .Ifitplacesanythingin/ a / u suchasa oamut vrrn pidfile,thenitshouldstartafterb o m s : otic

CodeListing4.5:Exampledepend()function dpn( eed){ neoamut edlclon atrboms feotic }

StandardFunctions
Nexttothed p n ( functionality,youalsoneedtodefinethes a t ) eed) t r ( function.Thisonecontainsallthe commandsnecessarytoinitializeyourservice.Itisadvisabletousethee e i ande n functionstoinformthe bgn ed useraboutwhatishappening:
CodeListing4.6:Examplestart()function sat){ tr( i$R_M}rsat f["{CCD"="etr"] te hn #Doehnncsetreursmrhnso,sat osmtigiaearsatrqieoetatptr f i eeiSatnysrie bgn"trigm_evc" satsoamnsateept/om_evc trtpdeotrxc/aht/ysrie\ pdie/aht/ypdie iflpt/om_ifl en? ed$ }

Both e e and p d i e xc i f l shouldbeusedinstartandstopfunctions.Iftheservicedoesnotcreateapidfile, thenuse m k i f l ifpossible,thoughyoushouldtestthistobesure.Otherwise,don'tusepidfiles.You aepdie canalsoadd q i t u e tothes a t s o a m n t r t p d e o options,butthisisnotrecommendedunlesstheserviceis extremelyverbose.Using q i t u e mayhinderdebuggingiftheservicefailstostart. AnothernotablesettingusedintheaboveexampleistocheckthecontentsoftheR _ M variable.Unlikethe CCD

previousinitscriptsystem,thenewero e r systemdoesnotsupportscriptspecificrestartfunctionality.Instead, pnc thescriptneedstocheckthecontentsoftheR _ M variabletoseeifafunction(beits a t ) CCD t r ( ors o ( )is tp) calledaspartofarestartornot.
Note:Makesurethat e e actuallycallsaserviceandnotjustashellscriptthatlaunchesservicesandexitsthat'swhatthe xc initscriptissupposedtodo.

Ifyouneedmoreexamplesofthes a t ) t r ( function,pleasereadthesourcecodeoftheavailableinitscriptsin your/ t / n t d e c i i . directory. Anotherfunctionyoucandefineiss o ( .Youarenotobligedtodefinethisfunctionthough!Ourinitsystemis tp) intelligentenoughtofillinthisfunctionbyitselfifyouuses a t s o a m n trtpdeo. Hereisanexampleofas o ( function: tp)
CodeListing4.7:Examplestop()function so( tp){ eeiSopnysrie bgn"tpigm_evc" satsoamnsoxc/aht/ysrie\ trtpdeotpeept/om_evc pdie/aht/ypdie iflpt/om_ifl en? ed$ }

Ifyourservicerunssomeotherscript(forexample,bash,python,orperl),andthisscriptlaterchangesnames(for example,f o p tof o o.y o ),thenyouwillneedtoadd n m tos a t s o a m n ae t r t p d e o .Youmustspecifythe namethatyourscriptwillbechangedto.Inthisexample,aservicestartsf o p ,whichchangesnamestof o o.y o:
CodeListing4.8:Aservicethatstartsthefooscript sat){ tr( eeiSatnysrp" bgn"trigm_cit satsoamnsateept/om_cit\ trtpdeotrxc/aht/ysrp pdie/aht/ypdienmo iflpt/om_iflaefo en? ed$ }

satsoamn t r t p d e o hasanexcellentmanpageavailableifyouneedmoreinformation:
CodeListing4.9:Gettingthemanpageforstartstopdaemon $mnsatsoamn atrtpdeo

Gentoo'sinitscriptsyntaxisbasedontheBourneAgainShell(bash)soyouarefreetousebashcompatible constructsinsideyourinitscript.However,youmaywanttowriteyourinitscriptstobePOSIXcompliant.Futureinit scriptsystemsmayallowsymlinking/ i / h b n s toothershellsbesidesbash.Initscriptsthatrelyonbashonly featureswillthenbreaktheseconfigurations.

AddingCustomOptions
Ifyouwantyourinitscripttosupportmoreoptionsthantheoneswehavealreadyencountered,youshouldaddthe optiontothee t a c m a d variable,andcreateafunctionwiththesamenameastheoption.Forinstance,to xr_omns supportanoptioncalledr s a t e a : etrdly
CodeListing4.10:Supportingtherestartdelayoption etacmad=rsatea" xr_omns"etrdly rsatea( etrdly){ so tp sep3at3scnsbfrtrigaan le#Wieodeoesatngi sat tr }

Important:Thefunctionr s a t ) e t r ( cannotbeoverriddeninopenrc!

ServiceConfigurationVariables
Youdon'thavetodoanythingtosupportaconfigurationfilein/ t / o f d e c c n . :ifyourinitscriptisexecuted,the followingfilesareautomaticallysourced(i.e.thevariablesareavailabletouse): /t/ofd<oriicit eccn./yuntsrp> /t/ofdbsc eccn./ai /t/ccn ecr.of Also,ifyourinitscriptprovidesavirtualdependency(suchasn t e ),thefileassociatedwiththatdependency(such as/ t / o f d n t e c c n . / e )willbesourcedtoo.

4.e.ChangingtheRunlevelBehaviour Whomightbenefitfromthis?
Manylaptopusersknowthesituation:athomeyouneedtostartn t e h whileyoudon'twanttostart e.t0 n t e h whileyou'reontheroad(asthereisnonetworkavailable).WithGentooyoucanaltertherunlevel e.t0 behaviourtoyourownwill. Forinstanceyoucancreateasecond"default"runlevelwhichyoucanbootthathasotherinitscriptsassignedtoit. Youcanthenselectatboottimewhatdefaultrunlevelyouwanttouse.

Usingsoftlevel
Firstofall,createtherunleveldirectoryforyoursecond"default"runlevel.Asanexamplewecreatetheo f i e fln runlevel:
CodeListing5.1:Creatingarunleveldirectory #mdr/t/ulvl/fln kiecrneesofie

Addthenecessaryinitscriptstothenewlycreatedrunlevels.Forinstance,ifyouwanttohaveanexactcopyofyour currentd f u t e a l runlevelbutwithoutn t e h : e.t0

CodeListing5.2:Addingthenecessaryinitscripts (oyalsriermdfutrneeoofiernee) Cplevcsfoealulvltflnulvl #cecrneesdfut d/t/ulvl/eal #frsrieidcudtdsrieofieoe oevcn*orpaead$evcflndn (eoeuwneevcrmofiernee) Rmvnatdsriefoflnulvl #rpaedlntehfln cudtee.t0ofie (ipaciesrieoflnulvl Dslyatvevcsfrofiernee) #rpaesofln cudthwofie (ataapeOtu) Prilsmlupt cifln apd|ofie dminmfln oanae|ofie oafln lcl|ofie nteh e.t0|

Eventhoughn t e h hasbeenremovedfromtheofflinerunlevel,u e mightwanttoattempttostartany e.t0 dv devicesitdetectsandlaunchtheappropriateservices,afunctionalitythatiscalledhotplugging.Bydefault,Gentoo doesnotenablehotplugging. Ifyoudowanttoenablehotplugging,butonlyforaselectedsetofscripts,usether _ o p u variablein chtlg /t/ccn: ecr.of
CodeListing5.3:Disablingdeviceinitiatedservicesin/etc/rc.conf #Alwntwaswlsayohrsriexettoemthne. loe.lnaelanteevc,ecphsacignt* #tehtlge obopugd

r_opu=ntwant* chtlg"e.ln!e." Note:Formoreinformationondeviceinitiatedservices,pleaseseethecommentsinside/ t / c c n . ecr.of

Nowedityourbootloaderconfigurationandaddanewentryfortheo f i e f l n runlevel.Forinstance,in /otgu/rbcn: bo/rbgu.of

CodeListing5.4:Addinganentryfortheofflinerunlevel tteGnoiuflnsg iletoLnxOfieUae roh00 ot(d,) kreh00/enl242ot/e/d3sflvlofie enl(d,)kre..5ro=dvhaotee=fln

Voil,you'reallsetnow.Ifyoubootyoursystemandselectthenewlyaddedentryatboot,theo f i e f l n runlevel willbeusedinsteadofthed f u t e a l one.

Usingbootlevel
Usingb o l v l o t e e iscompletelyanalogoustos f l v l o t e e .Theonlydifferencehereisthatyoudefineasecond "boot"runlevelinsteadofasecond"default"runlevel.

5.EnvironmentVariables
5.a.EnvironmentVariables? Whattheyare
Anenvironmentvariableisanamedobjectthatcontainsinformationusedbyoneormoreapplications.Manyusers (andespeciallythosenewtoLinux)findthisabitweirdorunmanageable.However,thisisamistake:byusing environmentvariablesonecaneasilychangeaconfigurationsettingforoneormoreapplications.

ImportantExamples
ThefollowingtablelistsanumberofvariablesusedbyaLinuxsystemanddescribestheiruse.Examplevaluesare presentedafterthetable.
Variable PATH Description Thisvariablecontainsacolonseparatedlistofdirectoriesinwhichyoursystemlooksfor executablefiles.Ifyouenteranameofanexecutable(suchasl ,r p a e e e g )butthis s c u d t or m r e executableisnotlocatedinalisteddirectory,yoursystemwillnotexecuteit(unlessyouenterthe fullpathascommand,suchas/ i / s b n l ). ThisvariablehasthesamefunctionasP T ,butthisoneonlyliststhedirectoriesthatshouldbe AH checkedwhentherootuserentersacommand. Thisvariablecontainsacolonseparatedlistofdirectoriesinwhichthedynamicallinkersearches throughtofindalibrary. Thisvariablecontainsacolonseparatedlistofdirectoriesinwhichthem n a commandsearchesfor themanpages. Thisvariablecontainsacolonseparatedlistofdirectoriesinwhichthei f commandsearches no fortheinfopages. Thisvariablecontainsthepathtotheprogramusedtolistthecontentsoffilesthrough(suchas l s orm r ). es oe Thisvariablecontainsthepathtotheprogramusedtochangethecontentsoffileswith(suchas n n orv ). ao i ThisvariablecontainsacolonseparatedlistofdirectorieswhichcontainKDEspecificmaterial. ThisvariablecontainsaspacedelimitedlistofdirectorieswhichshouldbeprotectedbyPortage duringupdates. ThisvariablecontainsaspacedelimitedlistofdirectorieswhichshouldnotbeprotectedbyPortage duringupdates.

ROOTPATH LDPATH MANPATH INFODIR PAGER EDITOR KDEDIRS CONFIG_PROTECT CONFIG_PROTECT_MASK

Belowyouwillfindanexampledefinitionofallthesevariables:
CodeListing1.1:Exampledefinitions PT=/i:urbn/s/oa/i:otbn/s/ae/i" AH"bn/s/i:urlclbn/p/i:urgmsbn ROPT=/bn/i:ursi:urbn/s/oa/bn/s/oa/i" OTAH"si:bn/s/bn/s/i:urlclsi:urlclbn

LPT=/i:urlb/s/oa/i:urlbgclbi8clnxgu323 DAH"lb/s/i:urlcllb/s/i/ci/66piun/.." MNAH"ursaemn/s/oa/hr/a" APT=/s/hr/a:urlclsaemn IFDR"ursaeif:urlclsaeif" NOI=/s/hr/no/s/oa/hr/no PGR"urbnls" AE=/s/i/es EIO=/s/i/i" DTR"urbnvm KEIS"ur DDR=/s" CNI_RTC=/s/1R/i/1/kottma/of\ OFGPOET"urX16lbX1xb/p/octcn /s/d/./hr/ofg/s/hr/em/e/eei/ofg urke31saecniursaetxftxgnrccni/\ /s/hr/em/e/ltxcni//s/hr/ofg ursaetxftxpae/ofgursaecni" CNI_RTC_AK"ecgof OFGPOETMS=/t/cn"

5.b.DefiningVariablesGlobally The/etc/env.dDirectory
Tocentralisethedefinitionsofthesevariables,Gentoointroducedthe/ t / n . directory.Insidethisdirectory ecevd youwillfindanumberoffiles,suchas0 b s c 5 c ,etc.whichcontainthevariablesneededbythe 0 a i ,0 g c applicationmentionedintheirname. Forinstance,whenyouinstalledg c c ,afilecalled0 g c 5 c wascreatedbytheebuildwhichcontainsthedefinitions ofthefollowingvariables:
CodeListing2.1:/etc/env.d/05gcc PT=/s/66piun/ci/." AH"uri8clnxgugcbn32 ROPT=/s/66piun/ci/." OTAH"uri8clnxgugcbn32 MNAH"ursaegcdt/66piun/./a" APT=/s/hr/caai8clnxgu32mn IFPT=/s/hr/caai8clnxgu32if" NOAH"ursaegcdt/66piun/./no C=gc C"c" CX"+" X=g+ LPT=/s/i/ci/66piun/.." DAH"urlbgclbi8clnxgu323

Otherdistributionstellyoutochangeoraddsuchenvironmentvariabledefinitionsin/ t / r f l orother ecpoie locations.Gentooontheotherhandmakesiteasyforyou(andforPortage)tomaintainandmanagethe environmentvariableswithouthavingtopayattentiontothenumerousfilesthatcancontainenvironmentvariables. Forinstance,wheng c c isupdated,the/ t / n . / 5 c fileisupdatedtoowithoutrequestinganyuser ecevd0gc interaction. ThisnotonlybenefitsPortage,butalsoyou,asuser.Occasionallyyoumightbeaskedtosetacertainenvironment variablesystemwide.Asanexamplewetaketheh t _ r x variable.Insteadofmessingaboutwith tppoy / t / r f l ,youcannowjustcreateafile(/ t / n . / 9 o a )andenteryourdefinition(s)init: ecpoie ecevd9lcl
CodeListing2.2:/etc/env.d/99local ht_rx=poysre.o:00 tppoy"rx.evrcm88"

Byusingthesamefileforallyourvariables,youhaveaquickoverviewonthevariablesyouhavedefinedyourself.

TheenvupdateScript
Severalfilesin/ t / n . definetheP T variable.Thisisnotamistake:whenyourune v u d t ,itwill ecevd AH npae appendtheseveraldefinitionsbeforeitupdatestheenvironmentvariables,therebymakingiteasyforpackages(or users)toaddtheirownenvironmentvariablesettingswithoutinterferingwiththealreadyexistingvalues. Thee v u d t scriptwillappendthevaluesinthealphabeticalorderofthe/ t / n . files.Thefilenames npae ecevd mustbeginwithtwodecimaldigits.
CodeListing2.3:Updateorderusedbyenvupdate 0ai9keev9lcl 0bsc9dn9oa ++ ++ PT=/i:urbn/s/d/./i:urlclbn AH"bn/s/i:urke32bn/s/oa/i"

Theconcatenationofvariablesdoesnotalwayshappen,onlywiththefollowingvariables:A A I C U E P T , D_NLD_AH A A O J C S P T ,C A S A H D D R ,P T ,L P T ,M N A H N O I ,I F P T ,R O P T , D _ B E T _ A H L S P T ,K E I S A H D A H A P T ,I F D R N O A H O T A H C N I _ R T C ,C N I _ R T C _ A K R L N _ A H R L N _ A H M S ,P G C N I _ A H O F G P O E T O F G P O E T M S ,P E I K P T ,P E I K P T _ A K K _ O F G P T andP T O P T .Forallothervariablesthelatestdefinedvalue(inalphabeticalorderofthefilesin YHNAH / t / n . )isused. ecevd Youcanaddmorevariablesintothislistofconcatenatevariablesbyaddingthevariablenametoeither CLNSPRTD O O _ E A A E orS A E S P R T D P C _ E A A E variables(alsoinsideanenv.dfile). Whenyourune v u d t ,thescriptwillcreateallenvironmentvariablesandplacethemin npae / t / r f l . n (whichisusedby/ t / r f l ).ItwillalsoextracttheinformationfromtheL P T ecpoieev ecpoie DAH variableandusethattocreate/ t / d s . o f e c l . o c n .Afterthis,itwillrunl c n i torecreatethe dofg / t / d s . a h fileusedbythedynamicallinker. ecl.occe Ifyouwanttonoticetheeffectofe v u d t immediatelyafteryourunit,executethefollowingcommandto npae updateyourenvironment.UserswhohaveinstalledGentoothemselveswillprobablyrememberthisfromthe installationinstructions:
CodeListing2.4:Updatingtheenvironment #evudt&sucecpoie npae&ore/t/rfl Note:Theabovecommandonlyupdatesthevariablesinyourcurrentterminal,newconsoles,andtheirchildren.Thus,ifyouare workinginX11,youwillneedtoeithertypes u c e c p o i e o r e / t / r f l ineverynewterminalyouopenorrestartXsothatallnew terminalssourcethenewvariables.Ifyouusealoginmanager,becomerootandtype/ t / n t d x m r s a t e c i i . / d e t r .Ifnot,you willneedtologoutandlogbackinforXtospawnchildrenwiththenewvariablevalues. Important:Youcannotuseshellvariableswhendefiningothervariables.ThismeansthingslikeF O " B R (where$ A is O=$A" BR anothervariable)areforbidden.

5.c.DefiningVariablesLocally UserSpecific
Youdonotalwayswanttodefineanenvironmentvariableglobally.Forinstance,youmightwanttoadd /oem_srbn h m / y u e / i andthecurrentworkingdirectory(thedirectoryyouarein)totheP T variablebutdon't AH wantallotherusersonyoursystemtohavethatintheirP T too.Ifyouwanttodefineanenvironmentvariable AH locally,youshoulduse~ . a h c / b s r or~ . a h p o i e /bs_rfl:
CodeListing3.1:ExtendingPATHforlocalusagein~/.bashrc (ooolwdbodrcoyiraestecretwrigdrcoy Aclnfloeynietrstetdahurnoknietr) PT=$PT}/oem_srbn" AH"{AH:hm/yue/i:

Whenyourelogin,yourP T variablewillbeupdated. AH

SessionSpecific
Sometimesevenstricterdefinitionsarerequested.Youmightwanttobeabletousebinariesfromatemporary directoryyoucreatedwithoutusingthepathtothebinariesthemselvesorediting~ . a h c / b s r fortheshorttimeyou needit. Inthiscase,youcanjustdefinetheP T variableinyourcurrentsessionbyusingthee p r command.Aslong AH xot asyoudon'tlogout,theP T variablewillbeusingthetemporarysettings. AH
CodeListing3.2:Definingasessionspecificenvironmentvariable #eprAH"{AH:hm/yue/m/s/i" xotPT=$PT}/oem_srtpurbn

C.WorkingwithPortage
1.FilesandDirectories

1.a.PortageFiles ConfigurationDirectives
Portagecomeswithadefaultconfigurationstoredin/ t / a e g o a s e c m k . l b l .Whenyoutakealookatit,you'll noticethatallPortageconfigurationishandledthroughvariables.WhatvariablesPortagelistenstoandwhatthey meanaredescribedlater. Sincemanyconfigurationdirectivesdifferbetweenarchitectures,Portagealsohasdefaultconfigurationfileswhich arepartofyourprofile.Yourprofileispointedtobythe/ t / a e p o i e e c m k . r f l symlinkPortage'configurationsare setinthem k . e a l s a e d f u t filesofyourprofileandallparentprofiles.We'llexplainmoreaboutprofilesandthe /t/aepoie e c m k . r f l directorylateron. Ifyou'replanningonchangingaconfigurationvariable,don'talter/ t / a e g o a s e c m k . l b l orm k . e a l s aedfut. Insteaduse/ t / a e c n whichhasprecedenceoverthepreviousfiles.You'llalsofinda ecmk.of /s/hr/otg/ofgmk.ofeape u r s a e p r a e c n i / a e c n . x m l .Asthenameimplies,thisismerelyanexamplefile Portagedoesnotreadinthisfile. YoucanalsodefineaPortageconfigurationvariableasanenvironmentvariable,butwedon'trecommendthis.

ProfileSpecificInformation
We'vealreadyencounteredthe/ t / a e p o i e e c m k . r f l directory.Well,thisisn'texactlyadirectorybutasymbolic linktoaprofile,bydefaultoneinside/ s / o t g / r f l s u r p r a e p o i e althoughyoucancreateyourownprofiles elsewhereandpointtothem.Theprofilethissymlinkpointstoistheprofiletowhichyoursystemadheres. AprofilecontainsarchitecturespecificinformationforPortage,suchasalistofpackagesthatbelongtothesystem correspondingwiththatprofile,alistofpackagesthatdon'twork(oraremaskedout)forthatprofile,etc.

UserSpecificConfiguration
WhenyouneedtooverridePortage'sbehaviourregardingtheinstallationofsoftware,youwillendupeditingfiles within/ t / o t g .Youarehighlyrecommendedtousefileswithin/ t / o t g andhighlydiscouragedto ecprae ecprae overridethebehaviourthroughenvironmentvariables! Within/ t / o t g youcancreatethefollowingfiles: ecprae p c a e m s whichliststhepackagesyouneverwantPortagetoinstall akg.ak p c a e u m s whichliststhepackagesyouwanttobeabletoinstalleventhoughtheGentoo akg.nak developershighlydiscourageyoufromemergingthem pcaeacp_ewrs a k g . c e t k y o d whichliststhepackagesyouwanttobeabletoinstalleventhoughthe packagehasn'tbeenfoundsuitableforyoursystemorarchitecture(yet) pcaeue a k g . s whichliststheUSEflagsyouwanttouseforcertainpackageswithouthavingtheentire systemusethoseUSEflags Thesedon'thavetobefilestheycanalsobedirectoriesthatcontainonefileperpackage.Moreinformationabout the/ t / o t g directoryandafulllistofpossiblefilesyoucancreatecanbefoundinthePortagemanpage: ecprae
CodeListing1.1:ReadingthePortagemanpage $mnprae aotg

ChangingPortageFile&DirectoryLocations
ThepreviouslymentionedconfigurationfilescannotbestoredelsewherePortagewillalwayslookforthose configurationfilesatthoseexactlocations.However,Portageusesmanyotherlocationsforvariouspurposes:build directory,sourcecodestorage,Portagetreelocation,... Allthesepurposeshavewellknowndefaultlocationsbutcanbealteredtoyourowntastethrough / t / a e c n .TherestofthischapterexplainswhatspecialpurposelocationsPortageusesandhowtoalter ecmk.of theirplacementonyourfilesystem.

Thisdocumentisn'tmeanttobeusedasareferencethough.Ifyouneed100%coverage,pleaseconsultthe Portageandm k . o f a e c n manpages:

CodeListing1.2:ReadingthePortageandmake.confmanpages $mnprae aotg $mnmk.of aaecn

1.b.StoringFiles ThePortageTree
ThePortagetreedefaultlocationis/ s / o t g .ThisisdefinedbythePORTDIRvariable.Whenyoustorethe urprae Portagetreeelsewhere(byalteringthisvariable),don'tforgettochangethe/ t / a e p o i e e c m k . r f l symboliclink accordingly. IfyoualterthePORTDIRvariable,youmightwanttoalterthefollowingvariablesaswellsincetheywillnotnotice thePORTDIRchange.ThisisduetohowPortagehandlesvariables:PKGDIR,DISTDIR,RPMDIR.

PrebuiltBinaries
EventhoughPortagedoesn'tuseprebuiltbinariesbydefault,ithasextensivesupportforthem.Whenyouask Portagetoworkwithprebuiltpackages,itwilllookforthemin/ s / o t g / a k g s u r p r a e p c a e .Thislocationis definedbythePKGDIRvariable.

SourceCode
Applicationsourcecodeisstoredin/ s / o t g / i t i e bydefault.Thislocationisdefinedbythe urpraedsfls DISTDIRvariable.

PortageDatabase
Portagestoresthestateofyoursystem(whatpackagesareinstalled,whatfilesbelongtowhichpackage,...)in /a/bpg v r d / k .Donotalterthesefilesmanually!ItmightbreakPortage'sknowledgeofyoursystem.

PortageCache
ThePortagecache(withmodificationtimes,virtuals,dependencytreeinformation,...)isstoredin / a / a h / d .Thislocationreallyisacache:youcancleanitifyouarenotrunninganyportagerelated vrcceeb applicationatthatmoment.

1.c.BuildingSoftware TemporaryPortageFiles
Portage'stemporaryfilesarestoredin/ a / m bydefault.ThisisdefinedbythePORTAGE_TMPDIRvariable. vrtp IfyoualterthePORTAGE_TMPDIRvariable,youmightwanttoalterthefollowingvariablesaswellsincetheywill notnoticethePORTAGE_TMPDIRchange.ThisisduetohowPortagehandlesvariables:BUILD_PREFIX.

BuildingDirectory
Portagecreatesspecificbuilddirectoriesforeachpackageitemergesinside/ a / m / o t g .Thislocationis vrtpprae definedbytheBUILD_PREFIXvariable.

LiveFilesystemLocation
BydefaultPortageinstallsallfilesonthecurrentfilesystem(/ ),butyoucanchangethisbysettingtheROOT environmentvariable.Thisisusefulwhenyouwanttocreatenewbuildimages.

1.d.LoggingFeatures

EbuildLogging
Portagecancreateperebuildlogfiles,butonlywhenthePORT_LOGDIRvariableissettoalocationthatiswritable byPortage(theportageuser).Bydefaultthisvariableisunset.Ifyoudon'tsetPORT_LOGDIR,thenyouwon't receiveanybuildlogswiththecurrentloggingsystem,thoughyoumayreceivesomelogsfromthenewe o .If lg youdohavePORT_LOGDIRdefinedandyouuseelog,youwillreceivebuildlogsandanylogssavedbyelog,as explainedbelow. Portageoffersfinegrainedcontroloverloggingthroughtheuseofe o : lg PORTAGE_ELOG_CLASSES:Thisiswhereyousetwhatkindsofmessagestobelogged.Youcanuse anyspaceseparatedcombinationofi f ,w r ,e r r o ,andq . n o a n r o ,l g a i f :Logs"einfo"messagesprintedbyanebuild no w r :Logs"ewarn"messagesprintedbyanebuild an err r o :Logs"eerror"messagesprintedbyanebuild lg o :Logsthe"elog"messagesfoundinsomeebuilds q :Logsthe"QANotice"messagesprintedbyanebuild a PORTAGE_ELOG_SYSTEM:Thisselectsthemodule(s)toprocessthelogmessages.Ifleftempty,logging isdisabled.Youcanuseanyspaceseparatedcombinationofs v ,c s o ,s s o ,m i , ae utm ylg al s v _ u m r ,andm i _ u m r .Youmustselectatleastonemoduleinordertouseelog. aesmay alsmay s v :Thissavesonelogperpackagein$ O T L G I / l g ae P R _ O D R e o ,or/ a / o / o t g / l g v r l g p r a e e o if $PORT_LOGDIRisnotdefined. c s o :Passesallmessagestoauserdefinedcommandin$PORTAGE_ELOG_COMMANDthis utm willbediscussedlater. s s o :Sendsallmessagestotheinstalledsystemlogger. ylg m i :Passesallmessagestoauserdefinedmailserverin$PORTAGE_ELOG_MAILURIthiswill al bediscussedlater.Themailfeaturesofelogrequire>=p r a e 2 1 1 otg... s v _ u m r :Similartos v ,butitmergesallmessagesin aesmay ae $OTLGI/lgsmaylg P R _ O D R e o / u m r . o ,or/ a / o / o t g / l g s m a y l g v r l g p r a e e o / u m r . o if $PORT_LOGDIRisnotdefined. m i _ u m r :Similartom i ,butitsendsallmessagesinasinglemailwhenemergeexits. alsmay al PORTAGE_ELOG_COMMAND:Thisisonlyusedwhenthec s o moduleisenabled.Hereiswhereyou utm specifyacommandtoprocesslogmessages.Notethatyoucanmakeuseoftwovariables:${PACKAGE}is thepackagenameandversion,while${LOGFILE}istheabsolutepathtothelogfile.Here'sonepossible usage: PORTAGE_ELOG_COMMAND="/path/to/loggerp'\${PACKAGE}'f'\${LOGFILE}'" PORTAGE_ELOG_MAILURI:Thiscontainssettingsforthem i modulesuchasaddress,user,password, al mailserver,andportnumber.Thedefaultsettingis"root@localhostlocalhost". Here'sanexampleforansmtpserverthatrequiresusernameandpasswordbasedauthenticationona particularport(thedefaultisport25): PORTAGE_ELOG_MAILURI="user@some.domainusername:password@smtp.some.domain:995" PORTAGE_ELOG_MAILFROM:Allowsyoutosetthe"from"addressoflogmailsdefaultsto"portage"if unset. PORTAGE_ELOG_MAILSUBJECT:Allowsyoutocreateasubjectlineforlogmails.Notethatyoucan makeuseoftwovariables:${PACKAGE}willdisplaythepackagenameandversion,while${HOST}isthe fullyqualifieddomainnameofthehostPortageisrunningon. Here'sonepossibleuse: PORTAGE_ELOG_MAILSUBJECT="package\${PACKAGE}wasmergedon\${HOST}withsome messages"
Important:Ifyouusede o i e n t c withPortage2.0.*,youmustcompletelyremoveenotice,asitisincompatiblewithelog.

2.ConfiguringthroughVariables

2.a.PortageConfiguration
Asnotedpreviously,Portageisconfigurablethroughmanyvariableswhichyoushoulddefinein/ t / a e c n . ecmk.of Pleaserefertothem k . o f a e c n manpageformoreandcompleteinformation:
CodeListing1.1:Readingthemake.confmanpage $mnmk.of aaecn

2.b.BuildspecificOptions ConfigureandCompilerOptions
WhenPortagebuildsapplications,itpassesthecontentsofthefollowingvariablestothecompilerandconfigure script: CFLAGS&CXXFLAGSdefinethedesiredcompilerflagsforCandC++compiling. CHOSTdefinesthebuildhostinformationfortheapplication'sconfigurescript MAKEOPTSispassedtothem k commandandisusuallysettodefinetheamountofparallelismused ae duringthecompilation.Moreinformationaboutthemakeoptionscanbefoundinthem k manpage. ae TheUSEvariableisalsousedduringconfigureandcompilationsbuthasbeenexplainedingreatdetailinprevious chapters.

MergeOptions
WhenPortagehasmergedanewerversionofacertainsoftwaretitle,itwillremovetheobsoletedfilesoftheolder versionfromyoursystem.Portagegivestheusera5seconddelaybeforeunmergingtheolderversion.These5 secondsaredefinedbytheCLEAN_DELAYvariable. Youcantelle e g tousecertainoptionseverytimeitisrunbysettingEMERGE_DEFAULT_OPTS.Some mre usefuloptionswouldbeask,verbose,tree,andsoon.

2.c.ConfigurationFileProtection Portage'sProtectedLocations
Portageoverwritesfilesprovidedbynewerversionsofasoftwaretitleifthefilesaren'tstoredinaprotected location.TheseprotectedlocationsaredefinedbytheCONFIG_PROTECTvariableandaregenerallyconfiguration filelocations.Thedirectorylistingisspacedelimited. Afilethatwouldbewritteninsuchaprotectedlocationisrenamedandtheuseriswarnedaboutthepresenceofa newerversionofthe(presumable)configurationfile. YoucanfindoutaboutthecurrentCONFIG_PROTECTsettingfromthee e g n o m r e i f output:
CodeListing3.1:GettingtheCONFIG_PROTECTsetting $eegno|geCNI_RTC= mreifrp'OFGPOET'

MoreinformationaboutPortage'sConfigurationFileProtectionisavailableintheCONFIGURATIONFILESsection ofthee e g manpage: mre

CodeListing3.2:MoreinformationaboutConfigurationFileProtection $mneeg amre

ExcludingDirectories
To'unprotect'certainsubdirectoriesofprotectedlocationsyoucanusetheCONFIG_PROTECT_MASKvariable.

2.d.DownloadOptions

ServerLocations
Whentherequestedinformationordataisnotavailableonyoursystem,PortagewillretrieveitfromtheInternet. Theserverlocationsforthevariousinformationanddatachannelsaredefinedbythefollowingvariables: GENTOO_MIRRORSdefinesalistofserverlocationswhichcontainsourcecode(distfiles) PORTAGE_BINHOSTdefinesaparticularserverlocationcontainingprebuiltpackagesforyoursystem AthirdsettinginvolvesthelocationofthersyncserverwhichyouusewhenyouupdateyourPortagetree: SYNCdefinesaparticularserverwhichPortageusestofetchthePortagetreefrom TheGENTOO_MIRRORSandSYNCvariablescanbesetautomaticallythroughthem r o s l c application. irreet Youneedtoe e g i r r e e t m r e m r o s l c firstbeforeyoucanuseit.Formoreinformation,seemirrorselect'sonline help:
CodeListing4.1:Moreinformationaboutmirrorselect #mroslcep irreethl

Ifyourenvironmentrequiresyoutouseaproxyserver,youcanusethehttp_proxy,ftp_proxyandRSYNC_PROXY variablestodeclareaproxyserver.

FetchCommands
WhenPortageneedstofetchsourcecode,itusesw e bydefault.Youcanchangethisthroughthe gt FETCHCOMMANDvariable. Portageisabletoresumepartiallydownloadedsourcecode.Itusesw e bydefault,butthiscanbealtered gt throughtheRESUMECOMMANDvariable. MakesurethatyourFETCHCOMMANDandRESUMECOMMANDstoresthesourcecodeinthecorrectlocation. Insidethevariablesyoushoulduse\${URI}and\${DISTDIR}topointtothesourcecodelocationanddistfiles locationrespectively. YoucanalsodefineprotocolspecifichandlerswithFETCHCOMMAND_HTTP,FETCHCOMMAND_FTP, RESUMECOMMAND_HTTP,RESUMECOMMAND_FTP,andsoon.

RsyncSettings
YoucannotalterthersynccommandusedbyPortagetoupdatethePortagetree,butyoucansetsomevariables relatedtothersynccommand: PORTAGE_RSYNC_OPTSsetsanumberofdefaultvariablesusedduringsync,eachspaceseparated. Theseshouldn'tbechangedunlessyouknowexactlywhatyou'redoing.Notethatcertainabsolutelyrequired optionswillalwaysbeusedevenifPORTAGE_RSYNC_OPTSisempty. PORTAGE_RSYNC_EXTRA_OPTScanbeusedtosetadditionaloptionswhensyncing.Eachoptionshould bespaceseparated. timeout=<number>:Thisdefinesthenumberofsecondsanrsyncconnectioncanidlebeforersync seestheconnectionastimedout.Thisvariabledefaultsto180butdialupusersorindividualswith slowcomputersmightwanttosetthisto300orhigher. excludefrom=/etc/portage/rsync_excludes:Thispointstoafilelistingthepackagesand/orcategories rsyncshouldignoreduringtheupdateprocess.Inthiscase,itpointsto /t/otg/sn_xlds e c p r a e r y c e c u e .PleasereadUsingaPortageTreeSubsetforthesyntaxof thisfile. quiet:Reducesoutputtothescreen verbose:Printsacompletefilelist progress:Displaysaprogressmeterforeachfile PORTAGE_RSYNC_RETRIESdefineshowmanytimesrsyncshouldtryconnectingtothemirrorpointedto bytheSYNCvariablebeforebailingout.Thisvariabledefaultsto3.

Formoreinformationontheseoptionsandothers,pleasereadm n r y c asn.

2.e.GentooConfiguration BranchSelection
YoucanchangeyourdefaultbranchwiththeACCEPT_KEYWORDSvariable.Itdefaultstoyourarchitecture's stablebranch.MoreinformationonGentoo'sbranchescanbefoundinthenextchapter.

PortageFeatures
YoucanactivatecertainPortagefeaturesthroughtheFEATURESvariable.ThePortageFeatureshavebeen discussedinpreviouschapters,suchasPortageFeatures.

2.f.PortageBehaviour ResourceManagement
WiththePORTAGE_NICENESSvariableyoucanaugmentorreducethenicevaluePortagerunswith.The PORTAGE_NICENESSvalueisaddedtothecurrentnicevalue. Formoreinformationaboutnicevalues,seethenicemanpage:
CodeListing6.1:Moreinformationaboutnice $mnnc aie

OutputBehaviour
TheNOCOLOR,whichdefaultsto"false",definesifPortageshoulddisabletheuseofcolouredoutput.

3.MixingSoftwareBranches
3.a.UsingOneBranch TheStableBranch
TheACCEPT_KEYWORDSvariabledefineswhatsoftwarebranchyouuseonyoursystem.Itdefaultstothestable softwarebranchforyourarchitecture,forinstancex 6 8. Werecommendthatyouonlyusethestablebranch.However,ifyoudon'tcareaboutstabilitythismuchandyou wanttohelpoutGentoobysubmittingbugreportstohttp://bugs.gentoo.org,readon.

TheTestingBranch
Ifyouwanttousemorerecentsoftware,youcanconsiderusingthetestingbranchinstead.TohavePortageuse thetestingbranch,adda~infrontofyourarchitecture. ThetestingbranchisexactlywhatitsaysTesting.Ifapackageisintesting,itmeansthatthedevelopersfeelthat itisfunctionalbuthasnotbeenthoroughlytested.Youcouldverywellbethefirsttodiscoverabuginthepackage inwhichcaseyoucouldfileabugreporttoletthedevelopersknowaboutit. Bewarethough,youmightnoticestabilityissues,imperfectpackagehandling(forinstancewrong/missing dependencies),toofrequentupdates(resultinginlotsofbuilding)orbrokenpackages.Ifyoudonotknowhow Gentooworksandhowtosolveproblems,werecommendthatyoustickwiththestableandtestedbranch. Forexample,toselectthetestingbranchforthex86architecture,edit/ t / a e c n andset: ecmk.of
CodeListing1.1:SettingtheACCEPT_KEYWORDSvariable ACP_EWRS"x6 CETKYOD=~8"

Ifyouupdateyoursystemnow,youwillfindoutthatlotsofpackageswillbeupdated.Mindyouthough:whenyou

haveupdatedyoursystemtousethetestingbranchthereisusuallynoeasywaybacktothestable,officialbranch (exceptforusingbackupsofcourse).

3.b.MixingStablewithTesting Thepackage.accept_keywordslocation
YoucanaskPortagetoallowthetestingbranchforparticularpackagesbutusethestablebranchfortherestofthe system.Toachievethis,addthepackagecategoryandnameyouwanttousethetestingbranchofin / t / o t g / a k g . c e t k y o d .Youcanalsocreateadirectory(withthesamename)andlist ecpraepcaeacp_ewrs thepackageinthefilesunderthatdirectory.Forinstance,tousethetestingbranchforg u e i : nmrc
CodeListing2.1:/etc/portage/package.accept_keywordssettingforgnumeric apofc/nmrc pfieguei

TestParticularVersions
Ifyouwanttouseaspecificsoftwareversionfromthetestingbranchbutyoudon'twantPortagetousethetesting branchforsubsequentversions,youcanaddintheversioninthep c a e a c p _ e w r s a k g . c e t k y o d location.Inthis caseyoumustusethe=operator.Youcanalsoenteraversionrangeusingthe<=,<,>or>=operators. Inanycase,ifyouaddversioninformation,youmustuseanoperator.Ifyouleaveoutversioninformation,you cannotuseanoperator. InthefollowingexampleweaskPortagetoacceptgnumeric1.2.13:
CodeListing2.2:Enablingaparticulargnumerictestversion =pfieguei..3 apofc/nmrc121

3.c.UsingMaskedPackages Thepackage.unmasklocation
Important:TheGentoodevelopersdonotsupporttheuseofthislocation.Pleaseexerciseduecautionwhendoingso.Support requestsrelatedtop c a e u m s and/orp c a e m s willnotbeanswered.Youhavebeenwarned. akg.nak akg.ak

WhenapackagehasbeenmaskedbytheGentoodevelopersandyoustillwanttouseitdespitethereason mentionedinthep c a e m s file(situatedin/ s / o t g / r f l s akg.ak u r p r a e p o i e bydefault),addthedesiredversion (usuallythiswillbetheexactsamelinefromp o i e )inthe/ t / o t g / a k g . n a k rfls e c p r a e p c a e u m s file(orina fileinthatdirectoryifitisadirectory). Forinstance,if= e a l h t a d 0 8 n t m i / o w y . ismasked,youcanunmaskitbyaddingtheexactsamelineinthe p c a e u m s location: akg.nak
CodeListing3.1:/etc/portage/package.unmask =ealhtad08 ntmi/owy. Note:Ifanentryin/ s / o t g / r f l s p c a e m s containsarangeofpackageversions,youwillneedtounmask urpraepoie/akg.ak onlytheversion(s)youactuallywant.Pleasereadtheprevioussectiontolearnhowtospecifyversionsinp c a e u m s . akg.nak

Thepackage.masklocation
Whenyoudon'twantPortagetotakeacertainpackageoraspecificversionofapackageintoaccountyoucan maskityourselfbyaddinganappropriatelinetothe/ t / o t g / a k g . a k e c p r a e p c a e m s location(eitherinthatfile orinafileinthisdirectory). Forinstance,ifyoudon'twantPortagetoinstallnewerkernelsourcesthang n o o r e . . . ,youadd etosucs2681 thefollowinglineatthep c a e m s location: akg.ak

CodeListing3.7:/etc/portage/package.maskexample >yenlgnoore... sskre/etosucs2681

4.AdditionalPortageTools
4.a.dispatchconf
dsacof i p t h c n isatoolthataidsinmergingthe. c g 0 0 < a e files.. c g 0 0 < a e filesare _f00_nm> _f00_nm> generatedbyPortagewhenitwantstooverwriteafileinadirectoryprotectedbytheCONFIG_PROTECTvariable. Withd s a c o f i p t h c n ,youareabletomergeupdatestoyourconfigurationfileswhilekeepingtrackofall changes.d s a c o f i p t h c n storesthedifferencesbetweentheconfigurationfilesaspatchesorbyusingtheRCS revisionsystem.Thismeansthatifyoumakeamistakewhenupdatingaconfigfile,youcanreverttotheprevious versionofyourconfigfileatanytime. Whenusingd s a c o f i p t h c n ,youcanasktokeeptheconfigurationfileasis,usethenewconfigurationfile,edit thecurrentoneormergethechangesinteractively.d s a c o f i p t h c n alsohassomeniceadditionalfeatures: Automaticallymergeconfigurationfileupdatesthatonlycontainupdatestocomments Automaticallymergeconfigurationfileswhichonlydifferintheamountofwhitespace Makecertainyouedit/ t / i p t h c n . o f e c d s a c o f c n firstandcreatethedirectoryreferencedbythearchivedir variable.
CodeListing1.1:Runningdispatchconf #dsacof ipthcn

Whenrunningd s a c o f i p t h c n ,you'llbetakenthrougheachchangedconfigfile,oneatatime.Pressu toupdate (replace)thecurrentconfigfilewiththenewoneandcontinuetothenextfile.Pressz tozap(delete)thenew configfileandcontinuetothenextfile.Onceallconfigfileshavebeentakencareof,d s a c o f i p t h c n willexit. Youcanalsopressq toexitanytime. Formoreinformation,checkoutthed s a c o f i p t h c n manpage.Ittellsyouhowtointeractivelymergecurrent andnewconfigfiles,editnewconfigfiles,examinedifferencesbetweenfiles,andmore.
CodeListing1.2:Readingthedispatchconfmanpage $mndsacof aipthcn

4.b.etcupdate
Youcanalsousee c u d t tomergeconfigfiles.It'snotassimpletouseasd s a c o f tpae i p t h c n ,noras featureful,butitdoesprovideaninteractivemergingsetupandcanalsoautomergetrivialchanges. However,unliked s a c o f t p a e i p t h c n ,e c u d t doesnotpreservetheoldversionsofyourconfigfiles.Onceyou updatethefile,theoldversionisgoneforever!Sobeverycareful,asusinge c u d t issignificantlylesssafe tpae thanusingd s a c o f ipthcn.
CodeListing2.1:Runningetcupdate #ecudt tpae

Aftermergingthestraightforwardchanges,youwillbepromptedwithalistofprotectedfilesthathaveanupdate waiting.Atthebottomyouaregreetedbythepossibleoptions:
CodeListing2.2:etcupdateoptions Peseetafloeiyetrnhorsodnubr laeslcietdtbneigtecrepnignme. (1txtoategleannie) oei)(3tuomrealrmiigfls oategNosmi) (5tuomreADntue'v':

Ifyouenter ,e c u d t willexitanddiscontinueanyfurtherchanges.Ifyouenter or ,alllisted 1 tpae 3 5 configurationfileswillbeoverwrittenwiththenewerversions.Itisthereforeveryimportanttofirstselectthe configurationfilesthatshouldnotbeautomaticallyupdated.Thisissimplyamatterofenteringthenumberlistedto theleftofthatconfigurationfile. Asanexample,weselecttheconfigurationfile/ t / e r c n : ecpa.of

CodeListing2.3:Updatingaspecificconfigurationfile Bgnigoifrneeweecpa.ofad/t/_f00_ercn einnfdfeecsbten/t/ercnnec.cg00pa.of [.] .. Edoifrneeweecpa.ofad/t/_f00_ercn nfdfeecsbten/t/ercnnec.cg00pa.of 1elcrgnlwtpae )Rpaeoiiaihudt 2eeeudt,keigoiiasi )Dltpaeepnrgnlas 3neatvlegrgnlwtpae )Itrcieymreoiiaihudt 4hwdfeecsaan )Soifrnegi

Youcannowseethedifferencesbetweenthetwofiles.Ifyoubelievethattheupdatedconfigurationfilecanbe usedwithoutproblems,enter1 .Ifyoubelievethattheupdatedconfigurationfileisn'tnecessary,ordoesn'tprovide anyneworusefulinformation,enter2 .Ifyouwanttointeractivelyupdateyourcurrentconfigurationfile,enter3 . Thereisnopointinfurtherelaboratingtheinteractivemerginghere.Forcompletenesssake,wewilllistthepossible commandsyoucanusewhileyouareinteractivelymergingthetwofiles.Youaregreetedwithtwolines(theoriginal one,andtheproposednewone)andapromptatwhichyoucanenteroneofthefollowingcommands:

CodeListing2.4:Commandsavailablefortheinteractivemerging e:Eihnuebtesosahdcrtdwtedr ddttesohvrin,eceoaeihahae. e:Eihnuebtesos bdttesohvrin. e:Eihnuetelfeso. ldtteshetvrin e:Eihnuetergtvrin rdtteshiheso. eEieeso. :dtanwvrin lUetelfeso. :shetvrin rUetergtvrin :shiheso. sSlnlnldomnlns :ietyicuecmoie. vVroeyicuecmoie. :ebslnldomnlns qQi. :ut

Whenyouhavefinishedupdatingtheimportantconfigurationfiles,youcannowautomaticallyupdatealltheother configurationfiles.e c u d t willexitifitdoesn'tfindanymoreupdateableconfigurationfiles. tpae

4.c.quickpkg
Withq i k k youcancreatearchivesofthepackagesthatarealreadymergedonyoursystem.Thesearchives ucpg canbeusedasprebuiltpackages.Runningq i k k isstraightforward:justaddthenamesofthepackagesyou ucpg wanttoarchive. Forinstance,toarchivec r ,o a e u l r g ,andp o p : rcs
CodeListing3.1:Examplequickpkgusage #qikkuloaepop ucpgcrrgrcs

Theprebuiltpackageswillbestoredin$ K D R u r p r a e p c a e / P G I (/ s / o t g / a k g s bydefault).Thesepackagesare placedin$ K D R < a e o y . PGI/ctgr>

5.DivertingfromtheOfficialTree
5.a.UsingaPortageTreeSubset ExcludingPackages/Categories
Youcanselectivelyupdatecertaincategories/packagesandignoretheothercategories/packages.Weachievethis

byhavingr y c s n excludecategories/packagesduringthee e g y c m r e s n step. Youneedtodefinethenameofthefilethatcontainstheexcludepatternsinthe e c u e f o variablein xldrm your/ t / a e c n . ecmk.of

CodeListing1.1:Definingtheexcludefilein/etc/make.conf PRAERYCETAOT=ecuefo=ecpraerycecue" OTG_SN_XR_PS"xldrm/t/otg/sn_xlds CodeListing1.2:Excludingallgamesin/etc/portage/rsync_excludes gms** ae/

Notehoweverthatthismayleadtodependencyissuessincenew,allowedpackagesmightdependonnewbut excludedpackages.

5.b.AddingUnofficialEbuilds DefiningaPortageOverlayDirectory
YoucanaskPortagetouseebuildsthatarenotofficiallyavailablethroughthePortagetree.Createanewdirectory (forinstance/ s / o a / o t g )inwhichyoustorethe3rdpartyebuilds.Usethesamedirectorystructureas urlclprae theofficialPortagetree! ThendefinePORTDIR_OVERLAYin/ t / a e c n andhaveitpointtothepreviouslydefineddirectory. ecmk.of WhenyouusePortagenow,itwilltakethoseebuildsintoaccountaswellwithoutremoving/overwritingthose ebuildsthenexttimeyourune e g y c mresn.

WorkingwithSeveralOverlays
Forthepoweruserswhodeveloponseveraloverlays,testpackagesbeforetheyhitthePortagetreeorjustwantto useunofficialebuildsfromvarioussources,thea p p r a e l y a packagebringsyoul y a ,atoolto potg/amn amn helpyoukeeptheoverlayrepositoriesuptodate. Firstinstallandconfigurel y a asshownintheOverlaysUsers'Guide,andaddyourdesiredrepositorieswith amn lyaa<vraae. amnoelynm> Supposeyouhavetworepositoriescalledj v (fortheindevelopmentjavaebuilds)ande t p s aa n a p (forthe applicationsdevelopedinhouseforyourenterprise).Youcanupdatethoserepositorieswiththefollowing command:
CodeListing2.1:Usinglaymantoupdateallrepositories #lyaS amn

Formoreinformationonworkingwithoverlays,pleasereadm n l y a andthelayman/overlayusers'guide. aamn

5.c.NonPortageMaintainedSoftware UsingPortagewithSelfMaintainedSoftware
Insomecasesyouwanttoconfigure,installandmaintainsoftwareyourselfwithouthavingPortageautomatethe processforyou,eventhoughPortagecanprovidethesoftwaretitles.Knowncasesarekernelsourcesandnvidia drivers.YoucanconfigurePortagesoitknowsthatacertainpackageismanuallyinstalledonyoursystem.This processiscalledinjectingandsupportedbyPortagethroughthe /t/otg/rfl/akg.rvdd e c p r a e p o i e p c a e p o i e file. Forinstance,ifyouwanttoinformPortageaboutg n o o r e . . 1 6 e t o s u c s 2 6 1 . whichyou'veinstalledmanually, addthefollowinglineto/ t / o t g / r f l / a k g . r v d d ecpraepoiepcaepoie:
CodeListing3.1:Examplelineforpackage.provided sskre/etosucs261. yenlgnoore..16

6.AdvancedPortageFeatures
6.a.Introduction
Formostusers,theinformationreceivedthusfarissufficientforalltheirLinuxoperations.ButPortageiscapableof muchmoremanyofitsfeaturesareforadvancedusersoronlyapplicableinspecificcornercases.Still,thatwould notbeanexcusenottodocumentthem. Ofcourse,withlotsofflexibilitycomesahugelistofpotentialcases.Itwillnotbepossibletodocumentthemall here.Instead,wehopetofocusonsomegenericissueswhichyoucanthenbendtofityourownneeds.Ifyouhave needformorespecifictweaksandtips,youmightfindthemontheGentooWiKiinstead. Most,ifnotalloftheseadditionalfeaturescanbeeasilyfoundbydiggingthroughthemanualpagesthatportage provides:
CodeListing2.10:Readinguponportagemanpages $mnprae aotg $mnmk.of aaecn

Finally,knowthattheseareadvancedfeatureswhich,ifnotworkedwithcorrectly,canmakedebuggingand troubleshootingverydifficult.Makesureyoumentiontheseifyouthinkyouhitabugandwanttoopenabugreport.

6.b.PerPackageEnvironmentVariables Using/etc/portage/env
Bydefault,packagebuildswillusetheenvironmentvariablesdefinedin/ t / a e c n ,suchasC L G , ecmk.of FAS M K O T andmore.Insomecasesthough,youmightwanttoprovidedifferentvariablesforspecificpackages.To AEPS doso,Portagesupportstheuseof/ t / o t g / n and/ t / o t g / a k g . n . ecpraeev ecpraepcaeev The/ t / o t g / a k g . n filecontainsthelistofpackagesforwhichyouwantdeviatingvariablesas ecpraepcaeev wellasaspecificidentifierthattellsPortagewhichchangesyouwant.Theidentifiernameyoupickyourself, Portagewilllookforthevariablesinthe/ t / o t g / n / i e t f e > e c p r a e e v < d n i i r file.

Example:Usingdebuggingforspecificpackages
Asanexample,weenabledebuggingforthem d a v d o m l y r e i i e / p a e package. Firstofall,wesetthedebuggingvariablesinafilecalled/ t / o t g / n / e u f a s e c p r a e e v d b g c l g .Thenameis arbitrarilychosen,butofcoursereflectsthereasonofthedeviationtomakeitmoreobviouslaterwhyadeviation wasputin.
CodeListing2.1:/etc/portage/env/debugcflagscontent CLG=2gbie FAS"Ogdpp" FAUE=$FAUE}nsrp ETRS"{ETRSoti"

Next,wetagthem d a v d o m l y r e i i e / p a e packagetousethiscontent:
CodeListing2.2:/etc/portage/package.envcontent mdavdomlyrdbgclg eiie/paeeufas

6.c.HookingIntheEmergeProcess Using/etc/portage/bashrcandaffiliatedfiles
WhenPortageworkswithebuilds,itusesabashenvironmentinwhichitcallsthevariousbuildfunctions(like src_prepare,src_configure,pkg_postinst,etc.).ButPortagealsoallowsyoutosetupabashenvironmentyourself. Theadvantageofusingyourownbashenvironmentisthatyoucanhookintheemergeprocessduringeachstepit performs.Thiscanbedoneforeveryemerge(through/ t / o t g / a h c e c p r a e b s r )orbyusingperpackage

environments(through/ t / o t g / n asdiscussedearlier). ecpraeev Tohookintheprocess,thebashenvironmentcanlistentothevariablesE U L _ H S ,C T G R aswellas BIDPAE AEOY thevariablesthatarealwaysavailableduringebuilddevelopment(suchasP F ,P ,...).Basedonthevaluesofthese variables,youcanthenexecuteadditionalsteps.

Example:UpdatingFileDatabases
Inthisexample,we'lluse/ t / o t g / a h c e c p r a e b s r tocallsomefiledatabaseapplicationstoensuretheir databasesareuptodatewiththesystem.Theapplicationsusedintheexamplearea d (anintrusiondetection ie tool)andu d t d (tousewithl c t ),butthesearemeantasexamples.DonotconsiderthisasaHOWTO paeb oae forAIDE) Touse/ t / o t g / a h c e c p r a e b s r forthiscase,weneedto"hook"inthep s r (afterremovaloffiles)and otm p s i s (afterinstallationoffiles)functions,becausethatiswhenthefilesonthefilesystemhavebeen otnt changed.
CodeListing3.1:Example/etc/portage/bashrc i$EUL_HS}="otnt]|$EUL_HS}="otm f["{BIDPAE"=psis"|["{BIDPAE"=psr"] te hn eh:alnieudtoudttaaae co":Cligadpaetpaeisdtbs" adpae ieudt eh:alnpaebtpaeisdtbs" co":Cligudtdoudttaaae udtd paeb f i

6.d.ExecutingTasksAftersync The/etc/portage/postsync.dlocation
Untilnowwe'vetalkedabouthookingintotheebuildprocesses.However,Portagealsohasanotherimportant function:updatingthePortagetree.InordertoruntasksafterupdatingthePortagetree,putascriptinside /t/otg/otycd e c p r a e p s s n . andmakesureitismarkedasexecutable.

Example:Runningeixupdate
Ifyoudidn'tusee x s n toupdatethetree,youcanstillhaveitsdatabaseupdatedafterrunninge e g iyc mre s n (ore e g e r y c yc m r e w b s n )byputtingasymlinkto/ s / i / i callede x u d t in urbnex ipae /t/otg/otycd ecpraepssn..
CodeListing4.1:Runningeixupdateafterasyncoperation #ls/s/i/iecpraepssn./ipae nurbnex/t/otg/otycdexudt Note:Ifyouratheruseadifferentname,youwillneedtomakeascriptthatcalls/ s / i / i p a e u r b n e x u d t instead.Thee x i binarylooksathowithasbeencalledtofindoutwhichfunctionithastoexecute.Ifyouputinasymlinktoe x i thatisn'tcalled e x u d t ,itwillnotruncorrectly. ipae

6.e.OverridingProfileSettings The/etc/portage/profilelocation
Bydefault,Gentoousesthesettingscontainedintheprofilepointedtoby/ t / a e p o i e e c m k . r f l (asymboliclink totherightprofiledirectory).Theseprofilesdefinebothspecificsettingsaswellasinheritsettingsfromother profiles(throughtheirp r n file). aet Byusing/ t / o t g / r f l ,youcanoverrideprofilesettingssuchasp c a e (whatpackagesare ecpraepoie akgs consideredtobepartofthesystemset),v r u l (defaultpackageswhenpullinginavirtual)andmore. itas

Example:AddingnfsutilstotheSystemSet

IfyouuseNFSbasedfilesystemsforrathercriticalfilesystems,youmightwanttohaven t f / f t l esnsuis "protected"asasystempackage,causingPortagetoheavilywarnyouifitwouldbedeleted. Toaccomplishthat,weaddthepackageto/ t / o t g / r f l / a k g s e c p r a e p o i e p c a e ,prependedwitha* :

CodeListing5.1:/etc/portage/profile/packagescontent *esnsuis ntf/ftl

6.f.ApplyingNonStandardPatches Usingepatch_user
Tomanageseveralebuildsinasimilarmanner,ebuilddevelopersuseeclasses(sortofshelllibraries)thatdefine commonlyusedfunctions.Oneoftheseeclassesise t l . c a s u i s e l s whichoffersaninterestingfunctioncalled eac_sr pthue. Thee a c _ s r p t h u e functionappliessourcecodepatchesthatarefoundin / t / o t g / a c e / c t g r > < a k g > v r i n [ < e i i n ] ,whateverdirectoryis ecpraepths<aeoy/pcae[<eso>rvso>] foundfirst.Sadly,notallebuildsautomaticallycallthisfunctionsojustputtingyourpatchinthislocationmightnot alwayswork. Luckily,withtheinformationprovidedabove,youcancallthisfunctionbyhookinginto,forinstance,thep e a e rpr phase.Thefunctioncanbecalledasmanytimesasyoulikeitwillonlyapplythepatchesonce.

Example:ApplyingPatchestoFirefox
Thew w c i n / i e o packageisoneofthefewthatalreadycalle a c _ s r wletfrfx p t h u e fromwithintheebuild,so youdonotneedtooverrideanythingspecific. Ifyouneedtopatchfirefox(forinstancebecauseadeveloperaskedyoutotosupportyouinabugyoureported), putthepatchin/ t / o t g / a c e / w l e t f r f x e c p r a e p t h s w w c i n / i e o (probablybesttousethefullname, includingversionsothatthepatchdoesnotinterferewithlaterversions)andrebuildfirefox.

D.GentooNetworkConfiguration
1.GettingStarted
1.a.Gettingstarted
Note:Thisdocumentassumesthatyouhavecorrectlyconfiguredyourkernel,itsmodulesforyourhardwareandyouknowthe interfacenameofyourhardware.Wealsoassumethatyouareconfiguringe h ,butitcouldalsobee h ,w a 0 t0 t 1 l n ,etc.

Togetstartedconfiguringyournetworkcard,youneedtotelltheGentooRCsystemaboutit.Thisisdoneby creatingasymboliclinkfromn t l ton t e h in/ t / n t d e.o e.t0 ecii..

CodeListing1.1:Symlinkingnet.eth0tonet.lo #cecii. d/t/ntd #lsntle.t0 ne.onteh

Gentoo'sRCsystemnowknowsaboutthatinterface.Italsoneedstoknowhowtoconfigurethenewinterface.All thenetworkinterfacesareconfiguredin/ t / o f d n t e c c n . / e .BelowisasampleconfigurationforDHCPandstatic addresses.

CodeListing1.2:Examplesfor/etc/conf.d/net #FrDC oHP cni_t0"hp ofgeh=dc" #FrsaiPuigCDoain ottcIsnIRntto cni_t0"9.6../4 ofgeh=1218072"

rue_t0"eali9.6.." otseh=dfutva121801 dssreseh=1218018888 n_evr_t0"9.6....." #FrsaiPuigntakntto ottcIsnemsoain cni_t0"9.6..ems5.5.5." ofgeh=121807ntak2525250 rue_t0"eali9.6.." otseh=dfutva121801 dssreseh=1218018888 n_evr_t0"9.6....." Note:IfyoudonotspecifyaconfigurationforyourinterfacethenDHCPisassumed. Note:CIDRstandsforClasslessInterDomainRouting.Originally,IPv4addresseswereclassifiedasA,B,orC.Theearly classificationsystemdidnotenvisionthemassivepopularityoftheInternet,andisindangerofrunningoutofnewunique addresses.CIDRisanaddressingschemethatallowsoneIPaddresstodesignatemanyIPaddresses.ACIDRIPaddresslooks likeanormalIPaddressexceptthatitendswithaslashfollowedbyanumberforexample,192.168.0.0/16.CIDRisdescribedin RFC1519.

Nowthatwehaveconfiguredourinterface,wecanstartandstopitusingthefollowingcommands:
CodeListing1.3:Startingandstoppingnetworkscripts #/t/ntdntehtr ecii./e.t0sat #/t/ntdntehtp ecii./e.t0so Important:Whentroubleshootingnetworking,takealookat/ a / o / c l g v r l g r . o .Unlessyouhaver _ o g r " O setin clge=N" / t / c c n ,youwillfindinformationonthebootactivitystoredinthatlogfile. ecr.of

Nowthatyouhavesuccessfullystartedandstoppedyournetworkinterface,youmaywishtogetittostartwhen Gentooboots.Here'showtodothis.Thelast"rc"commandinstructsGentootostartanyscriptsinthecurrent runlevelthathavenotyetbeenstarted.

CodeListing1.4:Configuringanetworkinterfacetoloadatboottime #rpaeadnteheal cudtde.t0dfut #r c

2.AdvancedConfiguration
2.a.AdvancedConfiguration
Thec n i _ t 0 o f g e h variableistheheartofaninterfaceconfiguration.It'sahighlevelinstructionlistforconfiguring theinterface(e h inthiscase).Eachcommandintheinstructionlistisperformedsequentially.Theinterfaceis t0 deemedOKifatleastonecommandworks. Here'salistofbuiltininstructions.
Command
nl ul no op

Description Donothing Iftheinterfaceisupandthereisanaddressthenabortconfigurationsuccessfully Addtheaddresstotheinterface Runthemodulewhichprovidesthecommand.Forexampled c willrunamodulethat hp providesDHCPwhichcanbeoneofeitherd c c ,d c i n orp m . hpd hlet up

anIPv4orIPv6address
d c ,a s ora i a hp dl p p (oracustom

commandfroma3rdpartymodule)

Ifacommandfails,youcanspecifyafallbackcommand.Thefallbackhastomatchtheconfigstructureexactly. Youcanchainthesecommandstogether.Herearesomerealworldexamples.
CodeListing1.1:Configurationexamples #AdnheP4adess digtreIvdrse cni_t0"9.6../4 ofgeh=1218022 1218032 9.6../4 1218042" 9.6../4 #AdnnIvdrsnwP6adess digaP4adesadtoIvdrse

cni_t0"9.6../4 ofgeh=1218022 42::::::6:9b 3101234578a 42::::::6:9c 3101234578a" #Keuenlasgedrs,ulshnefcos eporkresindadesnesteitraege #dwoasgnteiHPfDCalhnada onssinaohrvaDC.IHPfisted #saidrseemndbPP ttcadesdtrieyAIA cni_t0"op ofgeh=no dc" hp flbc_t0"ul alakeh=nl aia pp" Note:Whenusingthei c n i moduleandaddingmorethanoneaddress,interfacealiasesarecreatedforeachextraaddress. fofg Sowiththeabovetwoexamplesyouwillgetinterfacese h ,e h : ande h : .Youcannotdoanythingspecialwiththese t0 t01 t02 interfacesasthekernelandotherprogramswilljusttreate h : ande h : ase h . t01 t02 t0 Important:Thefallbackorderisimportant!Ifwedidnotspecifythen l optionthenthea i a ul p p commandwouldonlyberunifthe n o commandfailed. op Note:APIPAandDHCParediscussedlater.

2.b.NetworkDependencies
Initscriptsin/ t / n t d e c i i . candependonaspecificnetworkinterfaceorjustnet.Allnetworkinterfacesin Gentoo'sinitsystemprovidewhatiscallednet. If,in/ t / c c n ,r _ e e d s r c = Y S isset,thenallnetworkinterfacesthatprovidenetmustbe ecr.of cdpn_tit"E" activebeforeadependencyon"net"isassumedtobemet.Inotherwords,ifyouhavean t e h and e.t0 n t e h andaninitscriptdependson"net",thenbothmustbeenabled. e.t1 Ontheotherhand,ifr _ e e d s r c = N " c d p n _ t i t " O isset,thenthe"net"dependencyismarkedasresolvedthe momentatleastonenetworkinterfaceisbroughtup. Butwhataboutn t b 0 e . r dependingonn t e h andn t e h ?n t e h maybeawirelessorPPPdevice e.t0 e.t1 e.t1 thatneedsconfigurationbeforeitcanbeaddedtothebridge.Thiscannotbedonein/ t / n t d n t b 0 e c i i . / e . r as that'sasymboliclinkton t l . e.o Theanswerisdefininganr _ e d settingin/ t / o f d n t cne_ eccn./e.
CodeListing2.1:net.br0dependencyin/etc/conf.d/net r_edb0"e.t0nteh" cne_r=ntehe.t1

Thatalone,however,isnotsufficient.Gentoo'snetworkinginitscriptsuseavirtualdependencycallednettoinform thesystemwhennetworkingisavailable.Clearly,intheabovecase,networkingshouldonlybemarkedasavailable whenn t b 0 e . r isup,notwhentheothersare.Soweneedtotellthatin/ t / o f d n t e c c n . / e aswell:

CodeListing2.2:Updatingvirtualdependenciesandprovisionsfornetworking r_e_opoie"nt cntl_rvd=!e" r_e_t0poie"nt cnteh_rvd=!e" r_e_t1poie"nt cnteh_rvd=!e"

Foramoredetaileddiscussionaboutdependency,consultthesectionWritingInitScriptsintheGentooHandbook. Moreinformationabout/ t / c c n isavailableascommentswithinthatfile. ecr.of

2.c.Variablenamesandvalues
Variablenamesaredynamic.Theynormallyfollowthestructureof vral_{nefc|a|si|pa} a i b e $ i t r a e m c e s d a m c .Forexample,thevariabled c c _ t 0 h p d e h holdsthevaluefor dhcpcdoptionsforeth0andd c c _ s i holdsthevaluefordhcpcdoptionswhenanyinterfaceconnectstothe hpdesd ESSID"essid".

However,thereisnohardandfastrulethatstatesinterfacenamesmustbeethx.Infact,manywirelessinterfaces havenameslikewlanx,raxaswellasethx.Also,someuserdefinedinterfacessuchasbridgescanbegivenany name,suchasfoo.Tomakelifemoreinteresting,wirelessAccessPointscanhavenameswithnonalphanumeric charactersinthemthisisimportantbecauseyoucanconfigurenetworkingparametersperESSID. ThedownsideofallthisisthatGentoousesbashvariablesfornetworkingandbashcannotuseanythingoutside ofEnglishalphanumerics.TogetaroundthislimitationwechangeeverycharacterthatisnotanEnglishalpha numericintoa_ character. Anotherdownsideofbashisthecontentofvariablessomecharactersneedtobeescaped.Thiscanbeachivedby placingthe\ characterinfrontofthecharacterthatneedstobeescaped.Thefollowinglistofcharactersneedsto beescapedinthisway:" and\ ,' . InthisexampleweusewirelessESSIDastheycancontainthewidestscopeofcharacters.Weshallusethe ESSIDM \ N T y"E:
CodeListing3.1:variablenameexample (hsdeokuhoaninai) Tioswr,bttedmisivld dsdmi_y__E=M"\NT n_oanM__NT"y\\E" (hbvestedsdmioM\NTweieescr Teaoesthnoanty"Ehnawrlsad cnetoaPwoeESDiy"E) oncstnAhsSIsM\NT

3.ModularNetworking
3.a.NetworkModules
Wenowsupportmodularnetworkingscripts,whichmeanswecaneasilyaddsupportfornewinterfacetypesand configurationmoduleswhilekeepingcompatibilitywithexistingones. Modulesloadbydefaultifthepackagetheyneedisinstalled.Ifyouspecifyamoduleherethatdoesn'thaveits packageinstalledthenyougetanerrorstatingwhichpackageyouneedtoinstall.Ideally,youonlyusethemodules settingwhenyouhavetwoormorepackagesinstalledthatsupplythesameserviceandyouneedtopreferoneover theother.
Note:Allsettingsdiscussedherearestoredin/ t / o f d n t e c c n . / e unlessotherwisespecified. CodeListing1.1:Modulepreference #Peefofgoepot2 rfricnivrirue mdls"fofg oue=icni" #Yucnaspcfteoueonitrae oaloseiyohrmdlsfranefc #Ihscsepeeupoehpd ntiaewrfrpmvrdcc mdlseh=pm" oue_t0"up #Yucnaspcfhcoueoouefreapeyumyb oaloseiywihmdlsnttsoxmloae #uigasplcnrlnxwagtotoieescniuainbt snupiatoiulnnocnrlwrlsofgrtou #yusilwnocniuentokstigeSIsoitdwt. otlattofgrewretnsprESDascaeih mdls"icni" oue=!wofg

3.b.InterfaceHandlers
Weprovidetwointerfacehandlerspresently:i c n i andi r u e .Youneedoneofthesetodoanykindof fofg pot2 networkconfiguration. i c n i isinstalledbydefault(then t t o s fofg e o l packageispartofthesystemprofile).i r u e isamore pot2 powerfulandflexiblepackage,butit'snotincludedbydefault.
CodeListing2.1:Toinstalliproute2 #eegypsirue mressap/pot2

#Trfricnivriruefbtrntlesoerrfr opeefofgoepot2iohaeisaldapncpees #tspot2te oueiruehn mdls"fofg oue=icni"

Asbothi c n i andi r u e doverysimilarthingsweallowtheirbasicconfigurationtoworkwitheach fofg pot2 other.Forexampleboththebelowcodesnippetworkregardlessofwhichmoduleyouareusing.

CodeListing2.2:ifconfigandiproute2examples cni_t0"9.6../4 ofgeh=1218022" cni_t0"9.6..ems5.5.5." ofgeh=121802ntak2525250 #Waloseiybodat ecnaspcfracs cni_t0"9.6../4bd1218025 ofgeh=1218022r9.6..5" cni_t0"9.6..ems5.5.5.racs9.6..5" ofgeh=121802ntak2525250bodat1218025

3.c.DHCP
DHCPisameansofobtainingnetworkinformation(IPaddress,DNSservers,Gateway,etc)fromaDHCPserver. ThismeansthatifthereisaDHCPserverrunningonthenetwork,youjusthavetotelleachclienttouseDHCPand itsetsupthenetworkallbyitself.Ofcourse,youwillhavetoconfigureforotherthingslikewireless,PPPorother thingsifrequiredbeforeyoucanuseDHCP. DHCPcanbeprovidedbyd c i n ,d c c ,orp m .EachDHCPmodulehasitsprosandconshere'sa hlet hpd up quickrundown.
DHCP Module
dcin hlet

Package
nt e ms/hp icdc nt e ms/hpd icdcc nt e ms/up icpm

Pros MadebyISC,thesamepeoplewho maketheBINDDNSsoftware.Very configurable LongtimeGentoodefault,no relianceonoutsidetools,actively developedbyGentoo Lightweight,norelianceonoutside tools

Cons Configurationisoverlycomplex,softwareisquite bloated,cannotgetNTPserversfromDHCP,doesnot sendhostnamebydefault Canbeslowattimes,doesnotyetdaemonizewhenlease isinfinite Nolongermaintainedupstream,unreliable,especially overmodems,cannotgetNISserversfromDHCP

dcc hpd

pm up

IfyouhavemorethanoneDHCPclientinstalled,youneedtospecifywhichonetouseotherwisewedefaultto d c c ifavailable. hpd TosendspecificoptionstotheDHCPmodule,usem d l _ t 0 " . " o u e e h = . . (changemoduletotheDHCPmodule you'reusingi.e.d c c _ t 0 h p d e h ). WetryandmakeDHCPrelativelyagnosticassuchwesupportthefollowingcommandsusingthed c _ t 0 hpeh variable.Thedefaultisnottosetanyofthem: rlae e e s releasestheIPaddressforreuse nds o n don'toverwrite/ t / e o v c n ecrsl.of nnp o t don'toverwrite/ t / t . o f ecnpcn nns o i don'toverwrite/ t / p c n ecy.of
CodeListing3.1:SampleDHCPconfigurationin/etc/conf.d/net #OleddioaemrhnoeDCoueisald nyneefyuhvoetanHPmdlntle mdls"hpd oue=dcc" cni_t0"hp ofgeh=dc" dcc_t0"t1"#Tmotatr1eod hpdeh=0ieufe0scns dc_t0"eesonotoi"#Olenades hpeh=rlaendsnnpnnsnygtadrs Note:d c c andp m sendthecurrenthostnametotheDHCPserverbydefaultsoyoudon'tneedtospecifythisanymore. hpd up

3.d.ADSLwithPPPoE/PPPoA
FirstweneedtoinstalltheADSLsoftware.
CodeListing4.1:Installtheppppackage #eegeilppp mrentdau/p

Second,createthePPPnetscriptandthenetscriptfortheethernetinterfacetobeusedbyPPP:
CodeListing4.2:CreatingthePPPandethernetscripts #ls/t/ntdntlecii./e.p0 necii./e.o/t/ntdntpp #ls/t/ntdntlecii./e.t0 necii./e.o/t/ntdnteh

Besuretosetr _ e e d s r c to"YES"in/ t / c c n . cdpn_tit ecr.of Nowweneedtoconfigure/ t / o f d n t eccn./e.

CodeListing4.3:AbasicPPPoEsetup cni_t0nlSeiyyutentitrae ofgeh=ul(pcforehrenefc) cni_p0"p" ofgpp=pp ln_p0"t0Seiyyutentitrae ikpp=eh"(pcforehrenefc) puispp=ppe lgn_p0"po" uenm_p0'sr sraepp=ue' pswr_p0'asod asodpp=pswr' pp_p0" pdpp= nat ouh dfutot ealrue ueern speds hlof3 odf cidtmot6 hlieu0 lpehnevl1 ccoitra5 lpehalr ccofiue3 nacmocoscmoeltocmojnvcop ocopncpnbdopndfaenpopnvojcm" r_edpp=nteh" cne_p0"e.t0

Youcanalsosetyourpasswordin/ t / p / a e r t . ecppppsces
CodeListing4.4:Sample/etc/ppp/papsecrets #Te*imotn hsiprat "srae*pswr" uenm""asod

IfyouusePPPoEwithaUSBmodemyou'llneedtoemergeb 2 8 c l r 6 4 t .Pleaseread/ s / o t g / e urpraent d a u / p e t u h u b f l s R A M forinformationonhowtoproperlyconfigureit. ilpsedocs/ie/EDE

Important:PleasecarefullyreadthesectiononADSLandPPPin/ s / h r / o / p n c 0 8 3 ursaedcoer.. r / e . x m l . z .ItcontainsmanymoredetailedexplanationsofallthesettingsyourparticularPPPsetupwilllikelyneed. 1nteapeb2 Ofcourse,change0 8 3 r withtheversionofOpenRCinstalledonyoursystem. ..1

3.e.APIPA(AutomaticPrivateIPAddressing)
APIPAtriestofindafreeaddressintherange169.254.0.0169.254.255.255byarpingarandomaddressinthat rangeontheinterface.Ifnoreplyisfoundthenweassignthataddresstotheinterface. ThisisonlyusefulforLANswherethereisnoDHCPserverandyoudon'tconnectdirectlytotheinternetandall othercomputersuseAPIPA. ForAPIPAsupport,emergen t m s / p t l orn t a a y e / r i g eiciuis enlzrapn.
CodeListing5.1:APIPAconfigurationin/etc/conf.d/net

#TyDCisftaalhnflbcoAIA rHPfrtihtfistealaktPP cni_t0"hp ofgeh=dc" flbc_t0"pp" alakeh=aia #JssPP utueAIA cni_t0"pp" ofgeh=aia

3.f.Bonding
Forlinkbonding/trunkingemergen t m s / f n l v . eiciesae Bondingisusedtoincreasenetworkbandwidth.Ifyouhavetwonetworkcardsgoingtothesamenetwork,youcan bondthemtogethersoyourapplicationsseejustoneinterfacebuttheyreallyusebothnetworkcards.
CodeListing6.1:bondingconfigurationin/etc/conf.d/net #Toditraeoehr obnnefcstgte sae_od=eht1eh" lvsbn0"t0eht2 #YumyntwnoasgnIotebnenefc oaoattsinaPthodditrae cni_od=nl" ofgbn0"ul #Dpnneh,ehnt2ahymyrqieetacniuain eedot0t1adehsteaeurxrofgrto r_edbn0"e.t0ntehe.t2 cne_od=ntehe.t1nteh"

3.g.Bridging(802.1dsupport)
Forbridgingsupportemergen t m s / r d e u i s eicbigtl. Bridgingisusedtojoinnetworkstogether.Forexample,youmayhaveaserverthatconnectstotheinternetviaan ADSLmodemandawirelessaccesscardtoenableothercomputerstoconnecttotheinternetviatheADSL modem.Youcouldcreateabridgetojointhetwointerfacestogether.
CodeListing7.1:Bridgeconfigurationin/etc/conf.d/net #Cniuetebigmnbclooedtis ofgrhrde"art"frmreal bclb0"ef""ehlo0spof rt_r=std0stel""tf" #Tdotobigr oadprstrdeb0 big_r=eht1 rdeb0"t0eh" #Yuneocniueteprstulvleodcosntgtsatd oedtofgrhotonlausshpdeoetre cni_t0"ul ofgeh=nl" cni_t1"ul ofgeh=nl" #FnlygvhrdeadrsoolsHPael ialietebignadesyucudueDCswl cni_r=1218012" ofgb0"9.6../4 #Dpnnehnt1ahymyrqieetacniuain eedot0adehsteaeurxrofgrto r_edb0"e.t0nteh" cne_r=ntehe.t1 Important:Forusingsomebridgesetups,youmayneedtoconsultthevariablenamedocumentation.

3.h.MACAddress
Ifyouneedto,youcanchangetheMACaddressofyourinterfacesthroughthenetworkconfigurationfiletoo.
CodeListing8.1:MACAddresschangeexample #TehAdrsfteitrae ostteMCadesohnefc mceh=0:12:34:5 a_t0"01:23:45" #Tadmzhat3btsol ornoietelsyeny

mceh=rnonig a_t0"admedn" #Tadmzewehaepyiayeooncin(..fbe ornoiebtentesmhscltpfcnetoegir, #cpe,wrls),alvnos oprieesledr mceh=rnoaeid a_t0"admsmkn" #Tadmzewenhscltpfcnetoegir,cpe, ornoiebtenaypyiayeooncin(..fbeopr #wrls),alvnos ieesledr mceh=rnonkn" a_t0"admayid #FladmztoANN:smAdrseeeaeytia ulrnoiainWRIGoeMCadessgnrtdbhsmy #NTataxetd Ocsepce mceh=rnoul a_t0"admfl"

3.i.Tunnelling
Youdon'tneedtoemergeanythingfortunnellingastheinterfacehandlercandoitforyou.
CodeListing9.1:Tunnellingconfigurationin/etc/conf.d/net #FrGEtnes oRunl itne_p0"oegermt0.7.21ky0fffft5" punlvn=mdreoe27108.exfffftl25 #FrIIunl oPPtnes itne_p0"oeiieoe27108.t5" punlvn=mdpprmt0.7.22tl25 #Tofgrhnefc ocniueteitrae cni_p0"9.6..er121811 ofgvn=121802pe9.6.."

3.j.VLAN(802.1qsupport)
ForVLANsupport,emergen t m s / c n i . eicvofg VirtualLANisagroupofnetworkdevicesthatbehaveasiftheywereconnectedtoasinglenetworksegmenteven thoughtheymaynotbe.VLANmemberscanonlyseemembersofthesameVLANeventhoughtheymayshare thesamephysicalnetwork.
CodeListing10.1:VLANconfigurationin/etc/conf.d/net #SeiyteVAubrohnefcies pcfhLNnmesfrteitraelko #PesnueyuLNIsaeNTzradd laeesrorVADrOeopde vaseh=12 ln_t0"" #YucnasofgrhLN oalocniueteVA #sefrvofgmnpgooedtis eocniaaefrmreal vofgeh=stnm_yeVA_LSVDN_A" cni_t0"e_aetpLNPU_I_OPD vofgva1"e_lg1sters_a" cni_ln=stfa""e_gesmp26 #Cniueteitraeasa ofgrhnefcsuul cni_ln=121..ems5.5.5." ofgva1"7.631ntak2525240 cni_ln=121..ems5.5.5." ofgva2"7.621ntak2525240 Important:ForusingsomeVLANsetups,youmayneedtoconsultthevariablenamedocumentation.

4.WirelessNetworking
4.a.Introduction
WirelessnetworkingonLinuxisusuallyprettystraightforward.Therearetwowaysofconfiguringwifi:graphical clients,orthecommandline. Theeasiestwayistouseagraphicalclientonceyou'veinstalledadesktopenvironment.Mostgraphicalclients,

suchaswicdandNetworkManager,areprettyselfexplanatory.Theyofferahandypointandclickinterfacethatgets youonanetworkinjustafewseconds.
Note:w c offersacommandlineutilityinadditiontothemaingraphicalinterface.Youcangetitbyemergingw c withthe id id nuss c r e USEflagset.Thisw c u s s i d c r e utilityisparticularlyusefulforfolkswhodon'tuseagtkbaseddesktopenvironment, butstillwantaneasycommandlinetoolthatdoesn'trequirehandeditingconfigurationfiles.

However,ifyoudon'twanttouseagraphicalclient,thenyoucanconfigurewifionthecommandlinebyeditinga fewconfigurationfiles.Thistakesabitmoretimetosetup,butitalsorequiresthefewestpackagestodownload andinstall.Sincethegraphicalclientsaremostlyselfexplanatory(withhelpfulscreenshotsattheirhomepages), we'llfocusonthecommandlinealternatives. Youcansetupwirelessnetworkingonthecommandlinebyinstallingw r l s o l orw a s p l c n . ieestos p_upiat Theimportantthingtorememberisthatyouconfigurewirelessnetworksonaglobalbasisandnotaninterface basis. w a s p l c n isthebestchoice.Foralistofsupporteddrivers,readthewpa_supplicantsite. p_upiat w r l s o l supportsnearlyallcardsanddrivers,butitcannotconnecttoWPAonlyAccessPoints.Ifyour ieestos networksonlyofferWEPencryptionorarecompletelyopen,youmaypreferthesimplicityofw r l s o l . ieestos
Warning:Thel n x w a g i u l n n driverisnotsupportedbybaselayoutatthistime.Thisisbecausel n x w a g i u l n n haveits ownsetupandconfigurationwhichiscompletelydifferenttoeveryoneelse's.Thel n x w a g i u l n n developersarerumouredtobe changingtheirsetupovertow r l s o l ,sowhenthishappensyoumayusel n x w a g ieestos i u l n n withbaselayout.

4.b.WPASupplicant
WPASupplicantisapackagethatallowsyoutoconnecttoWPAenabledaccesspoints.
CodeListing2.1:Installwpa_supplicant #eegeieeswasplcn mrentwrls/p_upiat Important:YouhavetohaveC N I _ A K T O F G P C E enabledinyourkernelforw a s p l c n towork.Tryrunningg e p_upiat rp C N I _ A K T / s / r / i u / c n i toseeifyouhaveitenabledinyourkernel. OFGPCEursclnx.ofg Note:DependingonyourUSEflags,w a s p l c n caninstallagraphicalinterfacewritteninQt4,whichwillintegratenicely p_upiat withKDE.Togetit,rune h n t w r l s / p _ u p i a t q 4 > / t / o t g / a k g . s asroot co"eieeswasplcnt">ecpraepcaeue beforeemergingw a s p l c n . p_upiat

Nowwehavetoconfigure/ t / o f d n t e c c n . / e tosothatwepreferw a s p l c n overw r l s o l p_upiat ieestos (ifbothareinstalled,w r l s o l isthedefault). ieestos

CodeListing2.2:configure/etc/conf.d/netforwpa_supplicant #Peep_upiatoeieestos rfrwasplcnvrwrlsol mdls"p_upiat oue=wasplcn" #I'motnhtwelwasplcnhcrvrwhud tsiprattaetlp_upiatwihdieesol #bsnsi'oeygotgesne euigatsntvrodausigyt wasplcn_t0"Dawf" p_upiateh=mdii Note:Ifyou'reusingthehostapdriveryouwillneedtoputthecardinManagedmodebeforeitcanbeusedwith w a s p l c n correctly.Youcanusei c n i _ t 0 " o e m n g d toachievethisin/ t / o f d n t p_upiat wofgeh=mdaae" eccn./e.

Thatwassimple,wasn'tit?However,westillhavetoconfigurew a s p l c n itselfwhichisabitmoretricky p_upiat dependingonhowsecuretheAccessPointsarethatyouaretryingtoconnectto.Thebelowexampleistakenand simplifiedfrom/ s / h r / o / p _ u p i a t < e s o > w a s p l c n . o f g whichships ursaedcwasplcnvrin/p_upiatcn.z withw a s p l c n . p_upiat
CodeListing2.3:Anexample/etc/wpa_supplicant/wpa_supplicant.conf #Teblwlnoecagdohrieweuetok heoientbhnetewserfsowr

cr_nefc=vrrnwasplcn tlitrae/a/u/p_upiat #EsrhtolotcnrahPofgrto nuetanyroaedteWAcniuain cr_nefc_ru= tlitraegop0 #LtwasplcnaecrfsannnPslcin ep_upiattkaeocnigadAeeto a_cn1 psa= #SmlaePS,PKanACIpsprs,alwalvldcpes ipecs:WAPKSsaSIashaelolaiihr ntok{ ewr= si=sml" sd"ipe pk"eysceashae s=vrertpsprs" #Tehgehroiytesoeeaemthd hihrtepirthonrwrace pirt= roiy5 } #Smspeiu,btrqetSIpcfcsannfrAstaeet aearvosueusSDseiicnig(oPhtrjc #bodatSI) racsSD ntok{ ewr= si=scnsd sd"eodsi" sa_sd1 cnsi= pk"eysceashae s=vrertpsprs" pirt= roiy2 } #OlPSsue.Ayvldcpeobntosacpe nyWAPKisdnaiihrcmiainicetd ntok{ ewr= si=eape sd"xml" pooWA rt=P kymm=PS e_gtWAPK piws=CPTI arieCMKP gopCMKPWP0E4 ru=CPTIE14WP0 pk0bb1d2945a63c732da3ba3e28e00c2cb s=64e9a8f7a4a3b9094bd72e932b167a7b pirt= roiy2 } #PanetcnetonP,nEE821) litxoncin(oWAoIE0.X ntok{ ewr= si=panetts" sd"litxet kymm=OE e_gtNN } #SaeEeoncin(oWAoIE0.X hrdWPkycnetonP,nEE821) ntok{ ewr= si=saieet sd"ttcwpts" kymm=OE e_gtNN #KynqoerSIes esiutsaeACIky wpky=ace e_e0"bd" #Kypcfeihuutsaehxky esseiidwtotqoerees wpky=12345 e_e100000 wpky=1357913 e_e2"246802" wpt_eix0 e_xkyd= pirt= roiy5 } #SaeEeoncin(oWAoIE0.XsnhrdKy hrdWPkycnetonP,nEE821)uigSaee #IE0.1atetcto EE821uhniain ntok{ ewr= si=saieet" sd"ttcwpts2 kymm=OE e_gtNN wpky=ace e_e0"bd" wpky=12345 e_e100000 wpky=1357913 e_e2"246802" wpt_eix0 e_xkyd=

pirt= roiy5 at_l=HRD uhagSAE } #IS/dhcntokwtPoeTI BSaoewrihWANn/KP ntok{ ewr= si=tsdo" sd"etahc md= oe1 pooWA rt=P kymm=POE e_gtWANN piws=OE arieNN gopTI ru=KP pk"ertpsprs" s=sceashae }

4.c.WirelessTools InitialsetupandManagedMode
WirelessToolsprovideagenericwaytoconfigurebasicwirelessinterfacesuptotheWEPsecuritylevel.While WEPisaweaksecuritymethodit'salsothemostprevalent. WirelessToolsconfigurationiscontrolledbyafewmainvariables.Thesampleconfigurationfilebelowshould describeallyouneed.Onethingtobearinmindisthatnoconfigurationmeans"connecttothestrongest unencryptedAccessPoint"wewillalwaystryandconnectyoutosomething.
CodeListing3.1:Installwirelesstools #eegeieeswrlsol mrentwrls/ieestos Note:Althoughyoucanstoreyourwirelesssettingsin/ t / o f d w r l s thisguiderecommendsyoustorethemin eccn./iees /t/ofdnt eccn./e. Important:Youwillneedtoconsultthevariablenamedocumentation. CodeListing3.2:sampleiwconfigsetupin/etc/conf.d/net #Peewofgoep_upiat rfricnivrwasplcn mdls"wofg oue=icni" #CniueWPkyocesPitaldESDnSI2 ofgrEesfrAcsonscleSI1adESD #Yumycniueuo4WPky,btolaeatvt oaofgrptEesuny1cnbciea #aytmowupyadfutidxo1ostky[]adte niesesplealnef[]tee1nhn #aanatradocaghciekyt1 gifewrsthneteatveo[] #WotinaeyudfnteSI'oueWPkytehn1 edhsicsoeieohrESDstsEesohrta # #Peiigtekywt:masi'nACIkytewsEe rfxnheihsentsaSIe,ohrieaHXky # #ecoepcfepnscrtmseue npnseiidoeeuiy(otscr) #ecrsrcepcfeetitdscrtlatscr) netitdseiidrsrceeuiy(eseue kyESD=[]syukyeeky[]ecoe" e_SI1"1:orehre1npn kyESD=[]aabbccdky[]ecrsrce" e_SI2"1aabbccde1netitd #TeblwolokweesaovialcesPit heonywrhnwcnfraalbeAcsons #SmtmsmrhnoeAcsonsvsbeseneo oeieoetancesPitiiilowedt #dfnrfrereocneti eieapeerdodrtoncn peerdas"ESD''SI2" rfre_p='SI1ESD'

FinetuneAccessPointSelection
YoucanaddsomeextraoptionstofinetuneyourAccessPointselection,butthesearenotnormallyrequired. YoucandecidewhetherweonlyconnecttopreferredAccessPointsornot.Bydefaultifeverythingconfiguredhas

failedandwecanconnecttoanunencryptedAccessPointthenwewill.Thiscanbecontrolledbythe ascaeodr s o i t _ r e variable.Here'satableofvaluesandhowtheycontrolthis.

Value
ay n peerdny rfreol frerfre ocpeerd frerfreol ocpeerdny fren ocay

Description Defaultbehaviour WewillonlyconnecttovisibleAPsinthepreferredlist WewillforceablyconnecttoAPsinthepreferredorderiftheyarenotfoundinascan DonotscanforAPsinsteadjusttrytoconnecttoeachoneinorder Sameasf r e r f r e +connecttoanyotheravailableAP ocpeerd

Finallywehavesomeb a k i t a s l c l s _ p andu i u _ p n q e a selection.b a k i t a s l c l s _ p worksinasimilarwayto p e e r d a s n q e a isay s r f r e _ p .u i u _ p e orn valuethatsaysifasecondwirelessinterfacecanconnecttothe o sameAccessPointasthefirstinterface.

CodeListing3.3:blacklist_apsandunique_apexample #Smtmsyunvrwnocnetteticespit oeieoeeattoncocranacsons bakitas"ESD''SI4" lcls_p='SI3ESD' #Ioaemrhnoewrlsadoaafyuwn fyuhvoetanieescr,yucnsyioat #tloahcroascaewthaeAcsonrnt oalwecadtsoitihtesmcesPitoo #Vlerysnn" ausae"e"ad"o #Dfutiys eals"e" uiu_p"e" nqea=ys

AdHocandMasterModes
IfyouwanttosetyourselfupasanAdHocnodeifyoufailtoconnecttoanyAccessPointinmanagedmode,you candothattoo.
CodeListing3.4:fallbacktoadhocmode ahcesdeh=Tidooe do_si_t0"hsAhcNd"

WhataboutconnectingtoAdHocnetworksorrunninginMastermodetobecomeanAccessPoint?Here'sa configurationjustforthat!YoumayneedtospecifyWEPkeysasshownabove.
CodeListing3.5:sampleadhoc/masterconfiguration #Sttemdaemngd(eal)dhcoatr ehoecnbaaedfut,aormse #Ntaldiesspotalmds olrvruprloe md_t0"dhc oeeh=ao" #StteESDohnefc ehSIfteitrae #Iaaeoehsfrehnefcotyadcnetth nmngdmd,tiocsteitraetrnoncote #seiidESDadntiges pcfeSInohnle esdeh=Tidooe si_t0"hsAhcNd" #Wshnefyudntseiyoe euecanl3ioo'pcfn canleh=9 hne_t0"" Important:ThebelowistakenverbatimfromtheBSDwavelandocumentationfoundattheNetBSDdocumentation.Thereare14 channelspossibleWearetoldthatchannels111arelegalforNorthAmerica,channels113formostofEurope,channels1013 forFrance,andonlychannel14forJapan.Ifindoubt,pleaserefertothedocumentationthatcamewithyourcardoraccesspoint. Makesurethatthechannelyouselectisthesamechannelyouraccesspoint(ortheothercardinanadhocnetwork)ison.The defaultforcardssoldinNorthAmericaandmostofEuropeis3thedefaultforcardssoldinFranceis11,andthedefaultforcards soldinJapanis14.

TroubleshootingWirelessTools
Therearesomemorevariablesyoucanusetohelpgetyourwirelessupandrunningduetodriverorenvironment problems.Here'satableofotherthingsyoucantry.
Variable Default Description

Value
icni_t0 wofgeh ipi_t0 wrveh sepsa_t0 le_cneh sepascaeeh le_soit_t0 ascaets_t0 soit_eteh 0 5 MC A

Seetheiwconfigmanpagefordetailsonwhattosendi c n i wofg Seetheiwprivmanpagefordetailsonwhattosendi p i wrv Thenumberofsecondstosleepbeforeattemptingtoscan.Thisisneededwhenthe driver/firmwareneedsmoretimetoactivebeforeitcanbeused. ThenumberofsecondstowaitfortheinterfacetoassociatewiththeAccessPointbefore movingontothenextone SomedriversdonotresettheMACaddressassociatedwithaninvalidonewhenthey loseorattemptassociation.Somedriversdonotresetthequalitylevelwhentheylose orattemptassociation.ValidsettingsareM C q a i y A , u l t anda l l. Somedrivershavetoscaninadhocmode,soifscanningfailstrysettinga o here dhc Sendssomei p i commandstotheinterfacebeforescanning.Seetheiwprivman wrv pageformoredetails. Sendssomei p i commandstotheinterfaceafterscanning.Seetheiwprivmanpage wrv formoredetails.

sa_oeeh cnmd_t0 ipi_cnpeeh wrvsa_r_t0 ipi_cnps_t0 wrvsa_oteh

4.d.DefiningnetworkconfigurationperESSID
Sometimes,youneedastaticIPwhenyouconnecttoESSID1andyouneedDHCPwhenyouconnecttoESSID2. Infact,mostmodulevariablescanbedefinedperESSID.Here'showwedothis.
Note:Theseworkifyou'reusingWPASupplicantorWirelessTools. Important:Youwillneedtoconsultthevariablenamedocumentation. CodeListing4.1:overridenetworksettingsperESSID cni_SI1"9.6../4bd1218025 ofgESD=1218032r9.6..5" rue_SI1"eali9.6.." otsESD=dfutva121801 cni_SI2"hp ofgESD=dc" flbc_SI2"9.6../4 alakESD=1218342" flbc_ot_SI2"eali9.6.." alakrueESD=dfutva121831 #Waeienmsresadohrtigo ecndfnaeevrntehnsto #NT:DCiloerdhsnesi'odntto OEHPwlvrieteeulststloo dssresESD=121801121802 n_evr_SI1"9.6..9.6.." dsdmi_SI1"oedmi" n_oanESD=sm.oan dssac_oan_SI1"erhti.oansac.htdmi" n_erhdmisESD=sac.hsdmierhta.oan #YuoerdyteMCadesohcesPit ovriebhAdrsfteAcson #TiadfyugtifrnoainhthvhaeESD hshnyiooodfeetlctostaaetesmSI cni_012345"hp ofg012345=dc" dcc_012345"t1" hpd012345=0 dssres012345=121801121802 n_evr_012345"9.6..9.6.."

5.AddingFunctionality
3.a.Standardfunctionhooks
Fourfunctionscanbedefinedin/ t / o f d n t e c c n . / e whichwillbecalledsurroundingthes a t t p t r /s o operations. Thefunctionsarecalledwiththeinterfacenamefirstsothatonefunctioncancontrolmultipleadapters. Thereturnvaluesforthep e p ) r u ( andp e o n ) r d w ( functionsshouldbe0(success)toindicatethatconfiguration ordeconfigurationoftheinterfacecancontinue.Ifp e p ) r u ( returnsanonzerovalue,theninterfaceconfiguration willbeaborted.Ifp e o n ) r d w ( returnsanonzerovalue,thentheinterfacewillnotbeallowedtocontinue deconfiguration. Thereturnvaluesforthep s u ( andp s d w ( functionsareignoredsincethere'snothingtodoifthey otp) oton) indicatefailure. $ I A E issettotheinterfacebeingbroughtup/down.$ I V R is$ I A E convertedtovariablename {FC} {FA} {FC} bashallows.

CodeListing1.1:pre/postup/downfunctionexamplesin/etc/conf.d/net pep){ ru( #Tsoikohnefcroobigntu.hs etfrlnnteitraepirtrnigipTi #oloknsmewrdpesadrqiehtto nywrsooentokaatrneursteehol #pcaeteisald akgobntle. itto{FC}|geq'ikdtce:n'hn fehol$IAErpLneetdote ean"olnn$IAE,aotnofgrto" wrNiko{FC}brigcniuain rtr eun1 f i #Rmmeortrnsces eebrteun0oucs rtr eun0 } peon){ rdw( #TedfutihcitiotsoFotaddslo healntesrpstetfrNSronialw #dwigitraentaaeNthtiopcf onnnefcsihtcs.oetafyuseiya #peon)fntooiloerdhtlgcHrti,i rdw(ucinyuwlvrietaoi.eeisn #csotlati.. aeyusilwnt. isntfte fi_e_s/hn eroroieytmiewronecntso{FC} err"otflssesntokmutda'tp$IAE" rtr eun1 f i #Rmmeortrnsces eebrteun0oucs rtr eun0 } psu( otp){ #Tiucincudbsdoxml,teitrwt hsfntooleue,freapeorgseiha #dnmcDSsrieAohrpsiiiywudbo yaiNevc.nteosbltolet #sn/eevalochnefcsbogtu. edrciemineteitraeiruhp eun0 rtr } psdw( oton){ #Tiuciniotyhroopeees.ae' hsfntosmsleefrcmltns..Ihvnt #togtontignfytowttyt) huhfayhnitodihie rtr eun0 } Note:Formoreinformationonwritingyourownfunctions,pleaseread/ s / h r / o / p n c * n t e a p e b 2 ursaedcoer/e.xml.z.

3.b.WirelessToolsfunctionhooks
Note:ThiswillnotworkwithWPASupplicantbutthe$ E S D and$ E S D A } {SI} { S I V R variablesareavailableinthep s u ( otp) function.

Twofunctionscanbedefinedin/ t / o f d n t e c c n . / e whichwillbecalledsurroundingtheassociatefunction.The functionsarecalledwiththeinterfacenamefirstsothatonefunctioncancontrolmultipleadapters. Thereturnvaluesforthep e s o i t ( functionshouldbe0(success)toindicatethatconfigurationor rascae) deconfigurationoftheinterfacecancontinue.Ifp e s o i t ( returnsanonzerovalue,theninterface rascae) configurationwillbeaborted. Thereturnvalueforthep s a s c a e ) o t s o i t ( functionisignoredsincethere'snothingtodoifitindicatesfailure. $ E S D issettotheexactESSIDoftheAPyou'reconnectingto.$ E S D A } {SI} { S I V R is$ E S D convertedtoa {SI} variablenamebashallows.
CodeListing2.1:pre/postassociationfunctionsin/etc/conf.d/net pesoit( rascae){

#Teblwadwofgrtoaibeepue_SI heodstocniuainvralsla_srESD #adla_asESDhnterohcniueohSI nepps_SI.WehyaebtofgrdfrteESD #bigcnetdthnwuhICEPsrp enonceoteernteCSOLAcit lclueas oasrps easr\\\la_sr$ESDA}}" vlue="${epue_{SIVR\\ eaas\\\la_as$ESDA}}" vlps="${epps_{SIVR\\ i[{sr&{as]hn f[n$ue}&n$ps}]te i[!otcsobnlasrp]hn f[x/p/ic/i/epcit]te enFrLAupr,pesmrentms/icioeletuis ed"oEPspotlaeeegeiccsoarntcintl" rtr eun1 f i eno"atnoEPAtetcton\$ESD/\\/\" ifWiigfrLAuhniaino"{SI/\\/}" iotcsobnlasrp{sr{asrpLgnicrette f/p/ic/i/epcit$ue}$ps}|geq'oinorc'hn ean"oialdfr$ue} wrLgnFieo{sr" rtr eun1 f i f i rtr eun0 } psascae){ otsoit( #Tiuciniotyhroopeees.ae' hsfntosmsleefrcmltns..Ihvnt #togtontignfytowttyt) huhfayhnitodihie rtr eun0 } Note:$ E S D and$ E S D A } {SI} { S I V R areunavailableinp e o n ) r d w ( andp s d w ( functions. oton) Note:Formoreinformationonwritingyourownfunctions,pleaseread/ s / h r / o / p n c * n t e a p e b 2 ursaedcoer/e.xml.z.

6.NetworkManagement
6.a.NetworkManagement
Ifyouandyourcomputerarealwaysonthemove,youmaynotalwayshaveanethernetcableorpluggedinoran accesspointavailable.Also,youmaywantnetworkingtoautomaticallyworkwhenanethernetcableispluggedin oranaccesspointisfound. Hereyoucanfindsometoolsthathelpyoumanagethis.
Note:Thisdocumentonlytalksabouti p u d f l g ,buttherearealternativessuchasn t l g e p u isalightweightalternative e p u .n t l g toi p u d f l g ,butitreliesonyourkernelnetworkdriversworkingcorrectly,andmanydriversdonot.

6.b.ifplugd
ifplugdisadaemonthatstartsandstopsinterfaceswhenanethernetcableisinsertedorremoved.Itcanalso managedetectingassociationtoAccessPointsorwhennewonescomeinrange.
CodeListing2.1:Installingifplugd #eegypsipud mressap/flg

Configurationforifplugdisfairlystraightforwardtoo.Theconfigurationfileisheldin/ t / o f d n t e c c n . / e .Runm n a ipud f l g fordetailsontheavailablevariables.Also,see/ s / h r / o / p n c * n t e a p e b 2 u r s a e d c o e r / e . x m l . z for moreexamples.

CodeListing2.2:Sampleifplugconfiguration (elct0wthnefcoboioe) Rpaeehihteitraetemntrd

ipudeh=.. flg_t0"." (omntrawrlsnefc) Toioieesitrae ipudeh=aimd=ln flg_t0"poewa"

Inadditiontomanagingmultiplenetworkconnections,youmaywanttoaddatoolthatmakesiteasytoworkwith multipleDNSserversandconfigurations.ThisisveryhandywhenyoureceiveyourIPaddressviaDHCP.Simply emergeo e r s l . pneov

CodeListing2.3:Installingopenresolv #eegpneov mreoersl

Seem n r s l c n tolearnmoreaboutitsfeatures. aeovof

Thecontentsofthisdocument,unlessotherwiseexpresslystated,arelicensedundertheCCBYSA2.5license.TheGentoo NameandLogoUsageGuidelinesapply.