LinuxFilesystemStructure—Release1.2 DanielQuinlan<Daniel.Quinlan@linux.org> FilesystemStandardGroup ABSTRACT TheopenanddistributedprocessinwhichtheLinuxoperatingsystemhas developedfostersrapidgrowthoftheoperatingsystem,applications,andintegrated distributions.Yet,thereexistsaneedforstandardizationoftheLinuxfilesystem structure.Thisdocumentaimstospecifystandardlocationsoffilesanddirectoriesin Linuxsystems.Astandardizedfilesystemstructureallowsusers,developers,and distributorstoobtainsystemcomponentsfromvarioussourcesthatwillworktogether assmoothlyasiftheyhadbeendevelopedunderacentralizeddevelopmentprocess.It alsoeasessystemadministration,developmentofsecondandthirdpartypackages,and thewritingofimplementationindependentdocumentation. March28,1995 LinuxFilesystemStructure March28,1995 Linuxisnotatrademark,andhasnoconnectiontoUNIX. UNIXisatrademarkoftheX/OpenCompany,Ltd. HP-UXisatrademarkofHewlett-Packard. NovellandNovellNetWarearetrademarksofNovell. SunOS,SunMicrosystems,SunNIS,SunRPC,andNFSaretrademarksofSunMicrosystems, Inc. SystemVandSVR4aretrademarksofAT&T. XWindowSystemisatrademarkofXConsortium,Inc. Allothercopyrightsareownedbytheirowners,unlessspecificallynotedotherwise.Useofaterm inthisdocumentshouldnotberegardedasaffectingthevalidityofanytrademarkorservice mark. Copyright◯c1994,1995DanielQuinlan Permissionisgrantedtocopyanddistributeverbatimcopiesofthisstandardprovidedthe copyrightandthispermissionnoticearepreservedonallcopies. PermissionisgrantedforFSSTNDcontributorsandparticipantstocopyanddistributemodified versionsofthisstandardundertheconditionsforverbatimcopyingforpurposesoffilesystem standardizationactivitiesonly,andsubjecttothoserestrictionslistedbelow. Thefollowingrestrictionsapplytoreproducingortransmittingthedocumentinanyform: •Allcopiesorportionsthereofmustidentifythedocument’stitleandsection,andmustbe accompaniedbythisentirenoticeinaprominentlocation. •Noportionofthisdocumentmayberedistributedinanymodifiedorabridgedformwithout thepriorapprovaloftheFSSTNDcoordinator. Anyentitiesseekingpermissiontodistributeanymaterialderivedfromthisdocument(otherthan verbatimcopies)mustcontacttheFSSTNDcoordinatorfortheappropriatelicense.

LinuxFilesystemStructure March28,1995 Preface StatusoftheStandard Thisisversion1.2oftheLinuxFilesystemStructure(FSSTND). Theguidelinesinthisstandardaresubjecttochange.Useofinformationcontainedinthis documentisatyourownrisk. OrganizationoftheStandard Thisstandardisdividedinto6parts: —General,includingastatementofscope,problems,objectives,andconformance requirements.(Section1) —TheFilesystem:astatementofsomeguidingprinciples.(Section2) —TheRootDirectory.(Section3) —The/usrHierarchy.(Section4) —The/varHierarchy.(Section5) —IssuesandAdditionalRationale.(Section6) TypographicalConventions Courierfontisusedforthenamesoffilesanddirectories. Componentsoffilenamesthatvaryarerepresentedbyadescriptionofthecontentsenclosedin "<"and">"characters,<thus>.Electronicmailaddressesarealsoenclosedin"<"and">"but areshownintheusualtypeface. Optionalcomponentsoffilenamesareenclosedin"["and"]"charactersandmaybecombined withthe"<"and">"convention.Forexample,ifafileexistedwhichcouldbeeitherbefound eitherwithorwithoutanextension,itmightberepresentedby<filename>[.<extension>]. Variablesubstringsofdirectorynamesandfilenamesareindicatedby"*". -1-LinuxFilesystemStructure March28,1995 1.General 1.1Scope ThisdocumentspecifiesastandardfilesystemstructureforLinuxsystems,includingthelocation offilesanddirectories,andthecontentsofsomesystemfiles. ThefilesystemstandardhasbeendesignedtobeusedbyLinuxdistributiondevelopers,package developers,andsystemimplementors.However,itisprimarilyintendedtobeareferenceandis notatutorialonhowtomanageaLinuxfilesystemordirectoryhierarchy. Thesearesomeofthefundamentalproblemsthatoriginallymotivatedthisstandardizationeffort: •TherewasnosinglewellacceptedLinuxdirectorystructure.Instead,thereweremany differentones,eachincompatiblewithoneanother. •Themostwidelyusedfilesystemhierarchieswerenotwellstructuredanddiffered gratuitouslyfrommoremoderndirectorystructure"standards"(suchasSystemV,BSD, SunOS,andothers). •ThefilesystemwasunfamiliaranddiscomfortingtoexperiencedUNIXusersand administratorswhohaveexperienceonmoremainstreamUNIXsystems. •ThelackofregularitywasalsoconfusingfornewcomerstoLinux,especiallythosecoming fromanon-UNIXbackground. •AnyincompatibilitiesbetweenprimaryLinuxdistributionsandothersoftwarepackageswere typicallysolvedbymethodsofalessthanappealingnature. •Overall,symboliclinkswereusedmuchtoooftenwithinthefilesystemtofixproblems. (However,therearetimeswhensymboliclinksneedtobeusedtoensurebackward compatibilityortoallowspecificsystemstohaveanindividualfilesystemstructure.) Differencesinopinionariseinanystandardizationeffort.Theneedforconsensusandcommon practicewithintheLinuxcommunityshouldovershadowthesedifferences. ThisfilesystemstandardwasprimarilydevelopedwithintheFSSTNDmailinglistandpreviously, theFSSTNDchanneloftheLinux-activistsmailinglist.Inputandcommentswerereceivedfroma greatnumberofLinuxdevelopers,notedLinuxprogrammers,systemadministrators,andusers. Thosevolunteerswhohavecontributedextensivelytothisstandardarelistedattheendofthis document.Thisstandardrepresentstheconsensusviewofthoseandothercontributors. Thisstandardseekstoaddresstheseproblemsbydescribingawelldesignedfilesystemstructure thatwehopetheLinuxcommunitywillvoluntarilyfollow.Althoughthisstandardismore comprehensiveandcompletethananyotherpreviousattemptatstandardization,itwillprobably neverbetrulyfinished.TheneedsoftheLinuxcommunitywillcontinuallychangeinrelationto emergingtechnology.Itisalsopossiblethatbettersolutionstotheproblemsweaddresswillbe discoveredorthatoursolutionswillnolongerbethebestpossiblesolutions.Forthesereasons, theFSSTNDgroupplanstoreleasesupplementarydraftsinadditiontoperiodicupdatestothis document. CommentsrelatedtothisstandardarewelcomedbytheFSSTNDgroup.Anycommentsor suggestionsforchangesshouldbedirectedtotheFSSTNDcoordinator,orifyouprefer,anyofthe listedcontributors.TypographicalorgrammaticalcommentsshouldbedirectedtotheFSSTND coordinator. -2-LinuxFilesystemStructure March28,1995 ThereisalsoaFAQ,maintainedbyIanMcCloghrie,whichanswerssomeofthemorecommonly askedquestionsaboutthisstandard.IfyouwanttoimplementtheFSSTNDorifyouhavesome questions,pleasereadtheFSSTNDFAQfirst.ThisisavailableviaanonymousFTPat

tsx-11.mit.eduin/pub/linux/docs/linux-standards/fsstnd/FSSTND-FAQ.

PleasedonotsendmailtothemailinglistwithoutfirstcontactingtheFSSTNDcoordinatorora listedcontributor.Impropermessageswillnotbewellreceivedonthemailinglist. Questionsabouthowtointerpretitemsinthisdocumentmayoccasionallyarise.Ifyouhaveneed foraclarification,pleasecontacttheFSSTNDcoordinator.Sincethisstandardrepresentsthe consensusofmanyparticipants,itisimportanttomakecertainthatanyinterpretationalso representstheircollectiveopinion.Forthisreasonitmaynotbepossibletoprovideanimmediate responseunlesstheinquiryhasbeenthesubjectofpreviousdiscussion. TheFSSTNDcoordinatorisDanielQuinlan<Daniel.Quinlan@linux.org> 1.2SpecificProblems Naturally,whilestandardizingtheLinuxfilesystemstructure,thereweresomespecificproblems thatwesoughttocorrect.Herearesomeofthemostobviousandmajorones: •Theprimarybinarydirectories,/binand/usr/bin,donothavewelldefineddivisions betweenthem.Asaresult,thedistributionofthebinariesbetweenthesetwodirectories variesgreatlybetweentheLinuxdistributions. •Includingbothbinariesandconfigurationfilesin/etcmakesthisdirectorymoreconfusing andmoredifficulttomaintain,bothforinexperiencedusersandforsystemadministrators (especiallythosewithlargesystems). •Thedivisionbetweenwhatisasite-wideconfigurationfileandwhatisamachine-local configurationfileisdifficulttoestablish. •Manycommonimplementationsof/usrcannotbemountedread-onlybecausetheycontain variablefilesanddirectoriesthatneedtobewrittento. •InanetworkedenvironmentitisdesirabletoservesoftwaretoworkstationsviaNFS.Such filesystemsmayneedtobemountedread-onlysothataccidentsormaliceonone workstationcannotdamagethefilesontheserver.Thisrequiresidentificationand separationoffilesthatamachinemustwritetoandoffilesthatarespecifictoasingle machine. •CommonLinuxfilesystemstructuresweregenerallynotwellsuitedtonetworked installationswhichmayrequireread-onlycomponentswithinthefilesystem(primarilyinthe /usrhierarchy)orinvolvedisklessworkstations. Whilethesearesomeofthemajorproblemsweaddressed,therewerenumerousadditional problemsthatneededtobesolved.Thisstandardattemptstoaddressmanyofthoseother problems,buttheremaybesomethingthatwasoverlooked.Ifyouwishtobringsomethingto ourattention,pleasenotetherearesomethingsthathavebeendiscussedatlength,butwerenot includedinthisstandard. -3-LinuxFilesystemStructure March28,1995 1.3Objectives Intryingtosolvetheproblemsabove,severalobjectiveswereidentifiedthatneededtobe achievedinadditiontothemoretechnicalmatters.Thesegoalscomprisethecorrectionof outstandingproblemsaswellasthevalidationofthisstandard. •Solvetheproblemslistedabovewhilelimitingtransitionaldifficultieswhilemovingaway fromtheformerde-factostandards. •Gainapprovalofdistributors,developers,andotherimportantpeopleintheLinux community,aswellasencouragingthemtogiveustheirsuggestions. •ProvideastandardthatthewholeLinuxcommunitywillchoosetofollowbecauseitsolves theproblemsaboveandprovidesthemostsensiblestructureforthefilesystemsofLinux installations. Someoftheseobjectiveshavealreadybeenfullyorpartiallymetduetothelimiteddistributionof anadvancedrafttoanydeveloperwhorequestedone. 1.4HistoryandProgress TheoriginalmessagethatmotivatedthisefforttorestructuretheLinuxfilesystemwaswrittenby OlafKirsh<okir@monad.swb.de>onAugust2,1993,totheNORMALchanneloftheLinux activistsmailinglist. Soonthereafter,itwasdecidedthatthebestpossiblewaytoaccomplishthenecessary restructuringoftheLinuxfilesystemwouldbetocreateamailinglistforthepurposeof developingaconsensusstandard. Afteracomprehensivediscussion,withsurprisinglyfewflames,apreliminarydraftwaswritten. Withthehelpofseveraldedicatedpeople,thedraftwasfinishedandtheresultingdraftsubmitted totheFSSTNDchannelformorediscussion.Thefirstdraftwassubmittedtothechannelon September18,1993,byDanielQuinlan. AsthediscussioncontinuedandearlydraftsofFSSTNDrecommendationsweredevelopedfurther, contactswereestablishedwithaccessibleLinuxdistributorswhothenofferedtheirinputand supporttooureffort.ManyLinuxdevelopersagreedthatthisstandardizationeffortwas worthwhileandsupportedit. ThesearesomeofthedeveloperswhoaimtofollowtheFSSTNDstandard,partiallyorcompletely, listedinalphabeticalorder: •ATIMLinux/PRO FredN.vanKempenetal.<waltje@infomagic.com> •BOGUSLinux RikFaith,KevinE.Martin,andDougL.Hoffman<linux-bogus@cs.unc.edu> •DebianLinux IanA.Murdock<imurdock@debian.org> •LILObootloader WernerAlmesberger<almesber@nessie.cs.id.ethz.ch> -4-LinuxFilesystemStructure March28,1995 •MCCInterimLinux OwenLeBlanc<LeBlanc@mcc.ac.uk> •RedHatSoftwareLinux(RHSLinux) MarcEwing<marc@redhat.com> •SlackwareLinux PatrickJ.Volkerding<volkerdi@mhd1.moorhead.msus.edu> •TAMULinux DaveSafford<dave.safford@net.tamu.edu> •util-linuxpackage RikFaith<faith@cs.unc.edu> •YggdrasilPlug-and-PlayLinux AdamJ.Richter<adam@yggdrasil.com> 1.5ConformancewiththisDocument Thissectiondefinesthemeaningsoftheterms"compliant"and"compatible"withrespecttothis standard,andof"partial"complianceandconformance. An"implementation"herereferstoadistribution,aninstalledsystem,aprogram,apackage(or somesimilarpieceofsoftwareordata),orsomecomponentthereof. Animplementationisfullycompliantwiththisstandardifeveryrequirementinthisstandardis met.Everyfileordirectorywhichispartoftheimplementationmustbelocatedasspecifiedin thisdocument.Ifthecontentsofafilearedescribedheretheactualcontentsmustcorrespondto thedescription.Theimplementationmustalsoattempttofindanyfilesordirectories(externalto itself)primarilyorexclusivelyinthelocationspecifiedinthisstandard. Animplementationisfullycompatiblewiththisstandardifeveryfileordirectorywhichit containscanbefoundbylookinginthelocationspecifiedhereandwillbefoundwiththecontents asspecifiedhere,evenifthatisnottheprimaryorphysicallocationofthefileordirectoryin question.Theimplementationmust,whenitattemptstofindanyfilesordirectorieswhichare notpartofit,dosointhelocationspecifiedinthisstandard,thoughitmayalsoattempttofind itinother(non-standard)locations. Animplementationispartiallycompliantorcompatibleifitcomplieswithoriscompatiblewitha significantsubsetofthisdocument.Partialcomplianceorcompatibilityisonlyintendedtoapply todistributionsandnottoseparateprograms.Thephrase"asignificantsubset"isadmittedly subjective,andinborderlinecases,theconcernedpartyshouldcontacttheFSSTNDcoordinator. Itisanticipatedthatsomevariationwillbetoleratedinborderlinecases. InordertoqualifyaspartiallyFSSTNDcompliantorpartiallyFSSTNDcompatiblean implementationmustprovidealistofallplacesatwhichitandtheFSSTNDdocumentdifferin additiontoabriefexplanationofthereasoningforthisdifference.Thislistshallbeprovidedwith theimplementationinquestion,andalsomadeavailabletotheFSSTNDmailinglistorthe FSSTNDcoordinator. Theterms"must","should","contains","is"andsoforthshouldbereadasrequirementsfor complianceorcompatibility. -5-LinuxFilesystemStructure March28,1995 Notethatanimplementationdoesnotneedtocontainallthefilesanddirectoriesspecifiedinthis standardtobecompliantorcompatible.Itismerelynecessaryforthosefilesthatitdoescontain tobelocatedappropriately.Forexample,iftheext2filesystemisnotsupportedbyadistribution, theext2toolsneednotbeincluded,eventhoughtheyarementionedexplicitlyinthesectionon

/sbin.

Furthermore,certainportionsofthisdocumentareoptional.Inthiscasethiswillbestated explicitly,orindicatedwiththeuseofoneormoreof"may","recommend",or"suggest".Items markedasoptionalhavenobearingonthecomplianceorconformanceofanimplementation;they aresuggestionsmeanttoencouragecommonpractice,butmaybelocatedanywhereatthe implementor’schoice.

LinuxFilesystemStructure March28,1995 2.TheFilesystem TheUNIXfilesystemischaracterizedby: •Ahierarchicalstructure •Consistenttreatmentoffiledata •Protectionoffiledata ThisstandardontheLinuxfilesystemfollowsthesamebasicprinciplesthatmostUNIX filesystemsfollow.Notethatthisstandarddoesnotattempttoagreeineverypossiblerespect withanyparticularUNIXsystem’simplementation.However,manyaspectsofthisstandardare basedonideasfoundinUNIXandotherUNIX-likesystems. Thisisaftercarefulconsiderationofotherfactors,including: •CommonandsoundpracticesintheLinuxcommunity •Theimplementationofotherfilesystemstructures •Applicablestandards Itispossibletodefinetwoorthogonalcategorizationsoffiles:shareablevs.unshareableand variablevs.static. Shareabledataisthatwhichcanbesharedbetweenseveraldifferentmachines;unshareableisthat whichmustbelocaltoaparticularmachine.Forexample,userhomedirectoriesareshareable data,butdevicelockfilesarenot. Staticdataincludesbinaries,libraries,documentation,andanythingthatdoesnotchangewithout systemadministratorintervention;variabledataisanythingelsethatdoeschangewithoutsystem administratorintervention. Throughoutthisdocument,andinanywellplannedfilesystem,anunderstandingofthesebasic principleswillhelpguidethestructureandlenditadditionalconsistency. Thedistinctionbetweenshareableandunshareabledataisneededforseveralreasons: •Inanetworkedenvironment(i.e.,morethanonehostatasite),thereisagooddealofdata thatcanbesharedbetweendifferentmachinestosavespaceandeasethetaskof maintenance. •Inanetworkedenvironment,certainfilescontaininformationspecifictoasinglemachine. Thereforethesefilesystemscannotbeshared(withouttakingspecialmeasures). •Thede-factoimplementationofthefilesystemdidnotallowthe/usrhierarchytobe mountedread-onlybecauseitcontainedfilesanddirectoriesthatneedtobewrittento often.Thisisafactorthatmustbeaddressedwhenpartsof/usraresharedonanetwork ormountedread-onlybecauseofotherconsiderationssuchassecurity. The"shareable"distinctioncanbeusedtosupport,forexample: •A/usrpartition(orcomponentsof/usr)mounted(read-only)throughthenetwork(using NFS). -7-LinuxFilesystemStructure March28,1995 •A/usrpartition(orcomponentsof/usr)mountedfromread-onlymedia.ACD-ROMcan beconsideredaread-onlyfilesystemsharedwithotherLinuxsystems,usingthemailsystem asanetwork. The"static"versus"variable"distinctionaffectsthefilesystemin2majorways: •Since/containsbothvariableandstaticdata,itneedstobemountedread-write. •Sincethetraditional/usrcontainsbothvariableandstaticdata,andsincewemaywantto mountitread-only(seeabove),itisnecessarytoprovideamethodtohave/usrmounted read-only.Thisisdonethroughthecreationofa/varhierarchythatismountedread-write (orisapartofanotherread-writepartition,suchas/),takingovermuchofthe/usr partition’straditionalfunctionality. Summarizingchartwithexamples: shareableunshareable static/usr/etc /home/boot variable/var/spool/mail/var/run /var/spool/news/var/lock LinuxFilesystemStructure March28,1995 3.TheRootDirectory Thissectiondescribestherootdirectorystructure.Thecontentsoftherootfilesystemshouldbe adequatetoboot,restore,recover,and/orrepairthesystem: •Tobootasystem,enoughmustbepresenttomount/usrandothernon-essentialpartsof thefilesystem.Thisincludesutilities,configuration,bootloaderinformation,andother essentialstart-updata. •Toenablerecoveryand/orrepairofasystem,thoseutilitiesneededbyanexperienced maintainertodiagnoseandreconstructadamagedsystemshouldbepresentontheroot filesystem. •Torestoreasystem,thoseutilitiesneededtorestorefromsystembackups(onfloppy,tape, etc.)shouldbepresentontherootfilesystem. Theprimaryconcernusedtobalancetheseconsiderations,whichfavorplacingmanythingsonthe rootfilesystem,isthegoalofkeepingrootassmallasreasonablypossible.Forseveralreasons,it isdesirabletokeeptherootfilesystemsmall: •Itisoftenmountedfromverysmallmedia.Forexample,manyLinuxusersinstalland recoversystemsbymountingrootoffaRAMdisk,whichiscopiedfromasingle1.44Mor 1.2Mfloppydisk. •Therootfilesystemhasmanysystem-specificconfigurationfilesinit.Possibleexamples includeakernelthatisspecifictothesystem,adifferenthostname,etc.Thismeansthat therootfilesystemisn’talwaysshareablebetweennetworkedsystems.Keepingitsmallon networkedsystemsminimizestheamountofspacelostonserverstounshareablefiles.It alsoallowsworkstationswithsmallerlocalharddrives. •Whileyoumayhavetherootfilesystemonalargepartition,andmaybeabletofillitto yourheart’scontent,therewillbepeoplewithsmallerpartitions.Ifyouhavemorefiles installed,youmayfindincompatibilitieswithothersystemsusingrootfilesystemsonsmaller partitions.Ifyouareadeveloperthenyoumaybeturningyourassumptionintoaproblem foralargenumberofusers. •Diskerrorsthatcorruptdataontherootfilesystemareagreaterproblemthanerrorson anyotherpartition.Asmallrootfilesystemislesspronetocorruptionastheresultofa systemcrash. Thisdocumentascurrentlydraftedrequiresawritablerootfilesystem(primarilydueto /etc/mtab).However,thisdoesnotnecessitateafullylocallystoredroot.Therootpartition doesn’thavetobelocallystoredjusttobesystemspecific—forexample,itmightbemounted fromanNFSserver. Softwareshouldnevercreateorrequirespecialfilesorsubdirectoriesintherootdirectory.The Linuxfilesystemstructureprovidesmorethanenoughflexibilityforanypackage.Anypackage thatdoesoccupyadirectoryundertherootofthefilesystemsuffersfromsheerarrogance. -9-LinuxFilesystemStructure March28,1995 /—therootdirectory

bin

Essentialcommandbinaries

boot

Staticfilesofthebootloader

dev

Devicefiles

etc

Machine-localsystemconfiguration

home

Userhomedirectories

lib

Sharedlibraries

mnt

Mountpointoftemporarypartitions

proc

Processinformationpseudo-filesystem

root

Homedirectoryforroot

sbin

Essentialsystembinaries

tmp

Temporaryfiles

usr

Secondmajorhierarchy

var

Variabledata Eachdirectorylistedwillbediscussedindetailinaseparatesubsectionbelow./usrand/var eachhavetheirownmajorsectionsofthisdocument. TheLinuxkernelimageshouldbelocatedineither/or/boot.Ifitislocatedin/,we recommendusingthenamevmlinuxorvmlinuzwhichhavebeenusedinrecentLinuxkernel sourcepackages.Additionalinformationonkernelplacementcanbefoundinthesection regarding/boot,below. 3.1/bin:Essentialusercommandbinaries(forusebyallusers) /bincontainscommandsthatmaybeusedbyboththesystemadministratorandbyusers,but whicharerequiredinsingleusermode.Itmayalsocontaincommandswhichareusedindirectly byscripts. Allroot-onlybinariessuchasdaemons,init,getty,update,etc.shouldbeplacedin/sbinor /usr/sbin,dependingonwhethertheyareessential.Forfurtherdiscussionofthedefinitionof whatisessentialontherootfilesystem,pleasereadsection6,"IssuesandAdditionalRationale". Thereshouldbenosubdirectorieswithin/bin. Commandbinariesthatarenotessentialenoughtoplaceinto/binshouldbeplacedin/usr/bin, instead.Itemsthatareonlyusedbynon-rootusers(mail,chsh,etc.)arenotessentialenoughto beplacedintotherootpartition. Requiredfilesfor/bin: •Generalcommands: Thefollowingcommandshavebeenincludedbecausetheyareessential.Afewarepresent becauseoftheirtraditionalplacementin/bin.

{arch,cat,chgrp,chmod,chown,cp,date,dd,df,dmesg,echo,ed,false,
kill,ln,login,ls,mkdir,mknod,more,mount,mv,ps,pwd,rm,rmdir,
sed,setserial,sh,stty,su,sync,true,umount,uname}

If/bin/shisBash,then/bin/shshouldbeasymbolicorhardlinkto/bin/bashsince -10-LinuxFilesystemStructure March28,1995 Bashbehavesdifferentlywhencalledasshorbash.pdksh,whichmaybethe/bin/shon installdisks,shouldlikewisebearrangedwith/bin/shbeingasymlinkto/bin/ksh.The useofasymboliclinkinthesecasesallowsuserstoeasilyseethat/bin/shisnotatrue Bourneshell. Sincethede-factostandardlocationoftheC-shellis/bin/csh,ifandonlyifaC-shellor equivalent(suchastcsh)isavailableonthesystem,itshouldbeavailablebythename

/bin/csh./bin/cshmaybeasymboliclinkto/bin/tcshor/usr/bin/tcsh.

The[andtestcommandsarebuiltintoBash,pdksh,zsh,andrecentKornshells— essentiallyeveryBourneshellreplacementthereisforLinux.Thesecommandsshouldbe placedinto/usr/bin.(TheymustbeincludedasseparatebinarieswithanyLinuxsystem attemptingtocomplywiththePOSIX.2standard.) /bin/archshouldproducethesameoutputasuname-m,specificallyi386ori486forIntel andIntel-compatiblesystems. •Restorationcommands: Thesecommandshavebeenaddedtomakerestorationofasystempossible(providedthat/ isintact). {tar,gzip,gunzip(linktogzip),zcat(linktogzip)} Ifsystembackupsaremadeusingprogramsotherthangzipandtar,thentheroot partitionshouldcontaintheminimalnecessaryrestorationcomponents.Forinstance,many systemsshouldincludecpioasitisthenextmostcommonlyusedbackuputilityaftertar. Conversely,ifnorestorationfromtherootpartitioniseverexpected,thenthesebinaries maybeomitted(i.e.,aROMchiproot,mounting/usrthroughNFS).Ifrestorationofa systemisplannedthroughthenetwork,thenftportftp(alongwitheverythingnecessary togetaftpconnection)shouldbeavailableontherootpartition. Restorationcommandsmayappearineither/binor/usr/binondifferentLinuxsystems. •Networkingcommands: Thesearetheonlynecessarynetworkingbinariesthatbothrootanduserswillwantorneed toexecuteotherthantheonesin/usr/binor/usr/local/bin.

{domainname,hostname,netstat,ping}

3.2/boot:Staticfilesofthebootloader Thisdirectorycontainseverythingforbootexceptconfigurationfilesandthemapinstaller.In thesimplestsense,/bootisforanythingwhichisusedbeforethekernelexecs/sbin/init.This includessavedmasterbootsectors,sectormapfiles,andanythingelsethatisnotdirectlyedited byhand.Programsnecessarytoarrangeforthebootloadertobeabletobootafile(suchasthe lilomapinstaller)shouldbeplacedin/sbin.Configurationfilesforbootloadersshouldbe placedin/etc. Asalreadystatedabove,theLinuxkernelmayeitherbeplacedin/orin/boot.Itis recommendedthatthekernelimagebegivenamoredescriptivefilenameifplacedwithin/boot. -11-LinuxFilesystemStructure March28,1995 3.3/dev:Devicefiles Thisisthedevicedirectory.ItshouldcontainanentryforeverydevicethattheLinuxkernelis configuredtosupport. /devalsocontainsascriptnamedMAKEDEVwhichcancreatedevicesasneeded.Itmayalso containaMAKEDEV.localforanylocal-onlydevices. MAKEDEVshouldhaveprovisionsforcreatinganydevicespecialfilelistedintheLinux major/minornumberslist,notjustthosethataparticulardistributioninstalls. Symboliclinksin/devshouldnotbedistributedwithLinuxsystemsexceptasprovidedinthe Linuxdevicelist.Thisisbecauselocalsetupswilloftendifferfromthatonthedistributor’s developmentmachine.Also,ifadistributioninstallscriptconfiguresthesymboliclinksatinstall time,thesesymlinkswilloftennotgetupdatediflocalchangesaremadeinhardware.Whenused responsiblyatalocallevel,however,theycanbeputtogooduse. ThisstandardincorporatesbyreferencetheLinuxDeviceListwhichismaintainedbyH.Peter Anvin<Peter.Anvin@linux.org>,theLinuxDeviceRegistrar.Alldevicespecialfilesshould followthestandardinthatdocument,whichisavailableviaanonymousftpatftp.yggdrasil.comin

/pub/device-list.

3.4/etc:Machine-localsystemconfiguration /etccontainsconfigurationfilesanddirectories,whicharelocaltothecurrentsystem. Nobinariesshouldgodirectlyinto/etc.Binariesthatmightinthepasthavebeenfoundin/etc shouldbeplacedin/sbinor/usr/sbin.Thisincludessuchfilesasinit,getty,andupdate. Binariessuchashostnamethatareusedbyordinaryusersaswellastherootusershouldnotbe placedin/sbinbutin/bin. /etc—Machine-localsystemconfiguration

X11

ConfigurationfortheXWindowSystem

skel

Userskeletonconfiguration /etc/skelisthelocationforso-called"skeleton"userfilesthataregivenbydefaulttonewusers whenreceivinganaccount.Thisdirectorymaycontainsubdirectoriesfordifferentusergroups

(e.g.,/etc/skel/staffor/etc/skel/users).

/etc/X11istherecommendedlocationforallX11machine-localconfiguration.Thisdirectoryis necessarytoallowlocalcontrolif/usrismountedreadonly.Filesthatshouldbeinthis directoryincludeXconfig(and/orXF86Config)andXmodmap. Subdirectoriesof/etc/X11mayincludethoseforxdmandforanyotherprograms(somewindow managers,forexample)thatneedthem.Werecommendthatwindowmanagerswithonlyone configurationfilewhichisadefault.*wmrcfileshouldnameitsystem.*wmrc(unlessthereisa widely-acceptedalternativename)andnotuseasubdirectory.Anywindowmanager subdirectoriesshouldbeidenticallynamedtotheactualwindowmanagerbinary. /etc/X11/xdmholdstheconfigurationfilesforxdm.Thesearemostofthefilesnormallyfoundin -12-LinuxFilesystemStructure March28,1995 /usr/lib/X11/xdm;seeSection5,/var/lib/xdm,formoreinformation. Thefollowingsectionisintendedpartlytoilluminatethedescriptionofthecontentsof/etcwith anumberofexamples;itisdefinitelynotanexhaustivelist. Requiredfilesfor/etc: •Generalfiles: ThesefilesareneededonmostLinuxsystems.

{adjtime,csh.login,disktab,fdprm,fstab,gettydefs,group,inittab,
issue,ld.so.conf,lilo.conf,magic,motd,mtab,mtools,passwd,profile,
psdatabase,securetty,shells,syslog.conf,termcap,ttytype}

•Networkingfiles: ThesefilesshouldbeinstalledonmostLinuxsystems.

{exports,ftpusers,gateways,hosts,host.conf,hosts.equiv,hosts.lpd,
inetd.conf,networks,printcap,protocols,resolv.conf,rpc,services}

Therearetwomodelsforsetupofthe"rc"commandscriptswhichareinvokedbyinit(8) atboottime,the/etc/rc.*BSDmodelandthe/etc/rc.d/*SystemVmodel.Either modelmaybeused,oramixtureofthetwo. Systemsthatusetheshadowpasswordsuitewillhaveadditionalconfigurationfilesin/etc

(/etc/shadowandothers)and/usr/sbin(useradd,usermod,andothers).

3.5/home:Userhomedirectories(optional) /homeisafairlystandardconcept,butitisclearlyasite-specificfilesystem.Thesetupwilldiffer frommachinetomachine.Thissectiondescribesonlyasuggestedplacementforuserhome directories;neverthelesswerecommendthatallLinuxdistributionsusethisasthedefaultlocation forhomedirectories. Onsmallsystems,eachuser’sdirectoryistypicallyoneofthemanysubdirectoriesof/homesuch

as/home/smith,/home/torvalds,/home/operator,etc.

Onlargesystems(especiallywhenthe/homedirectoriesaresharedamongstmanymachinesusing NFS)itisusefultosubdivideuserhomedirectories.Subdivisionmaybeaccomplishedbyusing

subdirectoriessuchas/home/staff,/home/guests,/home/students,etc.

Differentpeopleprefertoplaceuseraccountsinavarietyofplaces.Therefore,noprogramshould relyonthislocation.Ifyouwanttofindoutauser’shomedirectory,youshouldusethe getpwent(3)libraryfunctionratherthanrelyingon/etc/passwdbecauseuserinformationmay bestoredremotelyusingsystemssuchasNIS. -13-LinuxFilesystemStructure March28,1995 3.6/lib:Essentialsharedlibrariesandkernelmodules The/libdirectorycontainsthosesharedlibraryimagesneededtobootthesystemandrunthe commandsintherootfilesystem. /lib—essentialsharedlibrariesandkernelmodules

modules

Loadablekernelmodules Thisincludes/lib/libc.so.*,/lib/libm.so.*,theshareddynamiclinker/lib/ld.so,and othersharedlibrariesrequiredbybinariesin/binand/sbin. Sharedlibrariesthatareonlynecessaryforbinariesin/usr(suchasanyXWindowbinaries)do notbelongin/lib.Onlythesharedlibrariesrequiredtorunbinariesin/binand/sbinshould behere.Thelibrarylibm.so.*mayalsobeplacedin/usr/libifitisnotrequiredbyanything

in/binor/sbin.

Forcompatibilityreasons,/lib/cppneedstoexistasareferencetotheCpreprocessorinstalled onthesystem.Theusualplacementofthisbinaryis

/usr/lib/gcc-lib/<target>/<version>/cpp./lib/cppcaneitherpointatthisbinary,orat

anyotherreferencetothisbinarywhichexistsinthefilesystem.(Forexample,/usr/bin/cppis alsooftenused.) Thespecificationfor/lib/modulesisforthcoming. 3.7/mnt:Mountpointfortemporarilymountedfilesystems Thisdirectoryisprovidedsothatthesystemadministratormaytemporarilymountfilesystemsas needed.Thecontentofthisdirectoryisalocalissueandshouldnotaffectthemannerinwhich anyprogramisrun. Werecommendagainsttheuseofthisdirectorybyinstallationprograms,andsuggestthata suitabletemporarydirectorynotinusebythesystemshouldbeusedinstead. 3.8/proc:Kernelandprocessinformationvirtualfilesystem Theprocfilesystemisbecomingthede-factostandardLinuxmethodforhandlingprocessand systeminformation,ratherthan/dev/kmemandothersimilarmethods.Westronglyencourage thisforthestorageandretrievalofprocessinformationaswellasotherkernelandmemory information. 3.9/root:Homedirectoryforroot(optional) /istraditionallythehomedirectoryoftherootaccountonUNIXsystems./rootisusedon manyLinuxsystemsandonsomeUNIXsystems.Therootaccount’shomedirectorymaybe determinedbydeveloperorlocalpreference.Obviouspossibilitiesinclude/,/root,and

/home/root.

Ifroot’shomedirectoryisnotstoredontherootpartitionitwillbenecessarytomakecertainit willdefaultto/ifitcannotbelocated. -14-LinuxFilesystemStructure March28,1995 Note:werecommendagainstusingtherootaccountformundanethingssuchasmailandnews, butrathertouseitsolelyforsystemsadministration.Forthisreason,werecommendthat subdirectoriessuchasMailandNewsnotappearintherootaccount’shomedirectory.We recommendthatmailforrootandpostmasterbeforwardedtoamoreappropriateuser. 3.10/sbin:Systembinaries(binariesoncekeptin/etc) Utilitiesusedforsystemadministration(andotherroot-onlycommands)arestoredin/sbin, /usr/sbin,and/usr/local/sbin./sbintypicallycontainsbinariesessentialforbootingthe systeminadditiontothebinariesin/bin.Anythingexecutedafter/usrisknowntobemounted (whentherearenoproblems)shouldbeplacedinto/usr/sbin.Local-onlysystemadministration binariesshouldbeplacedinto/usr/local/sbin. Decidingwhatthingsgoinsbindirectoriesissimple:Ifauserwillneedtorunit,thenitshould gosomewhereelse.Ifitwillonlyberunbysystemadministratorsorasrootfromsystem managementscripts,thenitshouldgoin/sbin(orin/usr/sbinor/usr/local/sbiniftheitem isnotvitaltosystemoperation). Filessuchaschfnwhichusersonlyoccasionallyuseshouldstillbeplacedin/usr/bin.ping, althoughitisabsolutelynecessaryforroot(networkrecoveryanddiagnosis)isoftenusedbyusers andshouldlivein/binforthatreason. Ordinaryusersshouldnothavetoplaceanyofthesbindirectoriesintheirpath. Werecommendthatusershavereadandexecutepermissionforeverythingin/sbinexcept, perhaps,certainsetuidandsetgidprograms.Thedivisionbetween/binand/sbinwasnot createdforsecurityreasonsortopreventusersfromseeingtheoperatingsystem,buttoprovidea goodpartitionbetweenbinariesthateveryoneusesandonesthatareprimarilyusedfor administrationtasks.Thereisnoinherentsecurityadvantageinmaking/sbinoff-limitsfor users. Requiredfilesfor/sbin: •Generalcommands:

{clock,getty,init,update,mkswap,swapon,swapoff,telinit}

•Shutdowncommands:

{fastboot,fasthalt,halt,reboot,shutdown}

(Oranycombinationoftheabove,solongasshutdownisincluded.) •Filesystemmanagementcommands:

{fdisk,fsck,fsck.*,mkfs,mkfs.*}
*=oneofext,ext2,minix,msdos,xiaandperhapsothers

•Secondextendedfilesystemcommands(optional): -15-LinuxFilesystemStructure March28,1995

{badblocks,dumpe2fs,e2fsck,mke2fs,mklost+found,tune2fs}

•Boot-loadermapinstaller:

{lilo}

•Networkingcommands:

{arp,ifconfig,route}

Optionalfilesfor/sbin: •Staticbinaries: Staticln(sln)andstaticsync(ssync)areusefulwhenthingsgowrong.Theprimaryuse ofsln(torepairincorrectsymlinksin/libafterapoorlyorchestratedupgrade)isnolonger amajorconcernnowthattheldconfigprogram(usuallylocatedin/usr/sbin)existsand canactasaguidinghandinupgradingthedynamiclibraries.Staticsyncisusefulinsome emergencysituations.Notethattheseneednotbestaticallycompiledversionsofthe standardlnandsync,butmaybe. Theldconfigbinaryisoptionalfor/sbinsinceasitemaychoosetorunldconfigatboot time,ratherthanonlywhenupgradingthesharedlibraries.(It’snotclearwhetherornotit isadvantageoustorunldconfigoneachboot.)Evenso,somepeoplelikeldconfig aroundforthefollowing(alltoocommon)situation: (1)I’vejustremoved/lib/<file>. (2)Ican’tfindoutthenameofthelibrarybecauselsisdynamicallylinked,I’musing ashellthatdoesn’thavelsbuilt-in,andIdon’tknowaboutusing"echo*"asa replacement. (3)Ihaveastaticsln,butIdon’tknowwhattocallthelink.

{ldconfig,sln,ssync}

•Miscellaneous: Soastocopewiththefactthatsomekeyboardscomeupwithsuchahighrepeatrateasto beunusable,kbdratemaybeinstalledin/sbinonsomesystems. SincethedefaultactioninthekernelfortheCtrl-Alt-Delkeycombinationisaninstanthard reboot,itisgenerallyadvisabletodisablethebehaviorbeforemountingtherootfilesystem inread-writemode.SomeinitsuitesareabletodisableCtrl-Alt-Del,butothersmay requirethectrlaltdelprogram,whichmaybeinstalledin/sbinonthosesystems.

{ctrlaltdel,kbdrate}

-16-LinuxFilesystemStructure March28,1995 3.11/tmp:Temporaryfiles /tmpisusedfortemporaryfiles,preferablyonafastdevice(amemorybasedfilesystem,for instance). The"persistence"ofthedatathatisstoredin/tmpisdifferentfromthatofdatawhichisstored in/var/tmp./tmpmaybecleanedoutatboottimeoratrelativelyfrequentintervals.Therefore, datastoredin/tmpshouldnotbeexpectedtoremainforanylongperiod. Programsshoulduse/tmpor/var/tmp(whichwasoriginally/usr/tmp)accordingtothe expectedrequirementsofthedata,butshouldnotrelyonanyparticularpersistenceforany temporarystoragedirectories. Systemadministratorsmaychoosetolink/tmptoanotherdirectory,suchas/var/tmp;thisis useful,forexample,toconservespaceontherootpartition.Ifthisisdone,thenthepersistenceof filesin/var/tmpshouldbeatleastaslongasfor/tmp. /tmpmaybeonaRAMdisk./var/tmpshouldneverbelocatedonaRAMdevice.

LinuxFilesystemStructure March28,1995 4.The/usrHierarchy /usristhesecondmajorsectionofthefilesystem./usrisshareable,read-onlydata.That meansthat/usrshouldbeshareablebetweenvariousmachinesrunningLinuxandshouldnotbe writtento.Anyinformationthatismachine-localorvarieswithtimeisstoredelsewhere. Nolargepackage(suchasTEXandGNUEmacs)shoulduseadirectsubdirectoryof/usr. Instead,thereshouldbeasubdirectorywithin/usr/lib(or/usr/local/libifitwasinstalled completelylocally)forthepurpose.AnexceptionismadefortheXWindowSystembecauseof considerableprecedentandwidely-acceptedpractice. /usr—Secondmajormountpoint(permanent)

X11R6

XWindowSystem,version11release6

X386

XWindowSystem,version11release5onx86Platforms

bin

Mostusercommands

dict

Wordlists

doc

Miscellaneousdocumentation

etc

Site-widesystemconfiguration

games

Gamesandeducationalbinaries

include

HeaderfilesincludedbyCprograms

info

GNUInfosystem’sprimarydirectory

lib

Libraries

local

Localhierarchy(emptyaftermaininstallation)

man

Onlinemanuals

sbin

Non-vitalsystemadministrationbinaries

share

Architecture-independentdata

src

Sourcecode Thefollowingsymboliclinkstodirectoriesmaybepresent.Thispossibilityisbasedontheneedto preservecompatibilitywitholdersystemsuntilallimplementationscanbeassumedtousethe /varhierarchy.

/usr/adm->/var/adm
/usr/preserve->/var/preserve
/usr/spool->/var/spool
/usr/tmp->/var/tmp
/var/spool/locks->/var/lock

Onceasystemnolongerrequiresanyoneoftheabovesymboliclinks,thelinkmayberemoved,if desired.Notably,ittakeslittleefforttocompletelyremove/usr/preservesinceonlyexandvi useit. -18-LinuxFilesystemStructure March28,1995 4.1/usr/X11R6:XWindowSystem,Version11Release6 ThishierarchyisreservedfortheXWindowSystem,version11release6,andrelatedfiles. /usr/X11R6—XWindowSystem(version11release6)

bin
doc
include
lib
man

TosimplifymattersandmakeXFree86morecompatiblewiththeXWindowSystemonother systems,thefollowingsymboliclinksshouldbepresent:

/usr/bin/X11->/usr/X11R6/bin
/usr/lib/X11->/usr/X11R6/lib/X11
/usr/include/X11->/usr/X11R6/include/X11

Ingeneral,softwareshouldnotbeinstalledormanagedviatheabovesymboliclinks.Theyare intendedforutilizationbyusersonly.ThedifficultyisrelatedtothereleaseversionoftheX WindowSystem—intransitionalperiods,itisimpossibletoknowwhatreleaseofX11isinuse. Forthesamereason,thereshouldnotbeasymboliclinkfrom/usr/X11pointingtothecurrentX WindowSystemhierarchy. 4.2/usr/X386:XWindowSystem,Version11Release5,onx86 platforms Thishierarchyisgenerallyidenticalto/usr/X11R6,exceptthatthe/usrsymboliclinksshouldbe absentif/usr/X11R6isinstalled. 4.3/usr/bin:Mostusercommands Thisistheprimarydirectoryofexecutablecommandsonthesystem. /usr/bin—Binariesthatarenotneededinsingle-usermode

mh

CommandsfortheMHmailhandlingsystem

X11

Symlinkto/usr/X11R6/bin

Becauseshellscriptinterpreters(invokedwith#!<path>onthefirstlineofashellscript)cannot relyonapath,itisadvantageoustostandardizethelocationofthem.TheBourneshellandCshellinterpretersarealreadyfixedin/bin,butPerl,Python,andTclareoftenfoundinmany

differentplaces./usr/bin/perl,/usr/bin/python,and/usr/bin/tclshouldreferencethe

perl,python,andtclshellinterpreters,respectively.Theymaybesymlinkstothephysical locationoftheshellinterpreters. -19-LinuxFilesystemStructure March28,1995 4.4/usr/dict:Wordlists Recommendedfilesfor/usr/dict:

{words}

TraditionallythisdirectorycontainsonlytheEnglishwordsfile,whichisusedbylook(1)and variousspellingprograms.wordsmayuseeitherAmericanorBritishspelling.Sitesthatrequire

bothmaylinkwordsto/usr/dict/american-englishor/usr/dict/british-english.

WordlistsforotherlanguagesmaybeaddedusingtheEnglishnameforthatlanguage,e.g., /usr/dict/french,/usr/dict/danish,etc.Theseshould,ifpossible,useanISO8859character setwhichisappropriateforthelanguageinquestion;ifpossibletheLatin1(ISO8859-1)character setshouldbeused(thisisoftennotpossible). Otherwordlists,suchastheweb2"dictionary"shouldbeincludedhere,ifpresent. Therationalebehindhavingonlywordlistshereisthattheyaretheonlyfilescommontoallspell checkers. 4.5/usr/etc:Site-widesystemconfiguration Storingconfigurationin/usr/etcforthesoftwarefoundin/usr/binand/usr/sbinisa problem.Itmakestheread-onlymountingof/usrthroughCD-ROMorNFSdeliveryvery difficultatbest. Onepossiblesolutionthatweconsideredwastocompletelyeliminate/usr/etcandspecifythat allconfigurationbestoredin/etc.Aproblemwiththisapproachisthatitdoesnotproperly anticipatethepossibilitythatmanysitesmaywanttohavesomeconfigurationfilesthatarenot machine-local. Weeventuallydecidedthat/etcshouldbetheonlydirectorythatisactuallyreferencedby programs(thatis,everythingshouldlookforconfigurationin/etcandnotin/usr/etc).Any configurationfilesthatneedtobesite-wideandarenotneededbefore/usrismounted(orinan emergencysituation)shouldthenbeplacedin/usr/etc.Then,specificfiles(in/etc)onspecific machinesmayormaynotbesymbolicallylinkedtoappropriateconfigurationfileslocatedin /usr/etc.Thisalsomeansthat/usr/etcistechnicallyanoptionaldirectoryinthestrictest sense,butwestillrecommendthatallLinuxsystemsincorporateit. Itisnotrecommendedfor/usr/etctocontainsymboliclinksthatpointtofilesin/etc.Thisis unnecessaryandinterfereswithlocalcontrolonmachinesthatsharea/usrdirectory. 4.6/usr/include:Directoryforstandardincludefiles. Thisiswhereallofthesystem’sgeneral-useincludefilesfortheCandC++programming languagesshouldbeplaced. -20-LinuxFilesystemStructure March28,1995

/usr/include—Includefiles
X11

Symlinkto/usr/X11R6/include/X11
arpa

ARPAnetdefinedprotocoldefinitions

asm

Symlinkto/usr/src/linux/include/asm-<arch>
bsd

BSDcompatibilityincludefiles

g++

GNUC++includefiles

gnu

GNUincludefiles

linux

Symlinkto/usr/src/linux/include/linux
net

Genericnetwork-relateddefinitions

netax25

+AX25(ARRLAX.25)specificdefinitions

netinet

TCP/IPspecificdefinitions

netipx

+IPX(NovellIPX/SPX)specificdefinitions

protocols

Protocoldefinitions(mostlyINET-based)

readline

TheGNUreadlinelibrary

rpc

SunMicrosystemsRPCdefinitions

rpcsvc

SunMicrosystemsRPCservicedefinitions

sys

Systemgenerationincludefiles ThearpasubdirectorycontainsprotocolheaderdefinitionsfortheARPAnetprotocols,TCP/IP conversionfunctions,definitionsforftp,telnetprototypes,andsimilarmaterial. Thenetsubdirectorycontainsgenericnetwork-relateddefinitions.Itdefinesthesystemkernel interface,protocolfamilydetails,etc. ThenetinetsubdirectorycontainsINET(DARPAInternet,whichisalsoknownasTCP/IP) specificdefinitions. ARRLAX.25isbetterknownaspacketradio.TheNovellIPX/SPXprotocolsarepartofthe NovellNetWarefileservices. 4.7/usr/lib:Librariesforprogrammingandpackages /usr/libincludesobjectlibraries,compilerprogrambinaries,andstaticdataofvariouskinds— bothexecutablecode(forexample,GCC’sinternalbinariesarelocatedunder/usr/lib/gcc-lib) andothertypesofdata. -21-LinuxFilesystemStructure March28,1995 /usr/lib—Librariesforprogrammingandpackages

X11

Symboliclinkto/usr/X11R6/lib/X11
emacs

StaticsupportfilesfortheGNUEmacseditor

games

Staticdatafilesfor/usr/games

groff

Libraries/directoriesforGNUgroff

gcc-lib

Systemspecificfiles/directoriesforGCC

kbd

Keyboardtranslationtablesandrelateddata

mh

LibrariesfortheMHmailhandlingsystem

news

Cnews/INN

smail

Smail

terminfo

Directoriesforterminfodatabase

texmf

TEX/MF(andLATEX)datalibraries

uucp

CommandsforUUCP

zoneinfo

Timezoneinformationandconfiguration Historically,/usr/libhasalsoincludedsomeexecutablecommandssuchassendmailand

makewhatis.

Sincemakewhatisisnotreferencedbyotherprograms,thereisnoproblemwithmovingittoa binarydirectory.Sinceusershavegoodcausetousemakewhatis,/usr/biniswhereitbelongs. Thecatmanbinary(whichreplacesthemakewhatisscriptonmanyLinuxsystems)shouldalsobe placedin/usr/bin. Thesendmailbinaryisreferencedbymanyprogramsbyitshistoricalname,/usr/lib/sendmail. Thisshouldbeasymboliclinktothestandardlocationformailtransferagentswithasendmailcompatiblecommandlineinterface,/usr/sbin/sendmail. SystemsusingSmailshouldplaceSmailin/usr/sbin/smail,and/usr/sbin/sendmailshouldbe asymboliclinktoit. ThisarrangementalsoconformstothenewstandardsendmaillocationasdefinedinSendmail 8.6.xand4.4BSD.Notethatthisplacementdemandsthat/usr/sbinand/usr/sbin/sendmail mustbeexecutablebynormalusers. Anyprogramorpackagewhichcontainsorrequiresdatathatdoesn’tneedtobemodifiedshould storethatdatain/usr/lib(or/usr/local/lib,ifinstalledlocally).Itisrecommendedthata subdirectorybeusedin/usr/libforthispurpose. Gamedatastoredin/usr/lib/gamesshouldbepurelystaticdata.Anymodifiablefiles,suchas scorefiles,gameplaylogs,andsoforth,shouldbeplacedin/var/lib.Ifnecessaryfor compatibilitywitholdBSD-stylegames,asymlinkfrom/usr/games/libto/usr/lib/gamescan beused. Note:Nohost-specificdatafortheXWindowSystemshouldbestoredin/usr/lib/X11(whichis really/usr/X11R6/lib/X11).Host-specificconfigurationfilessuchasXconfigorXF86Config shouldbestoredin/etc/X11.Thisshouldincludeconfigurationdatasuchassystem.twmrceven ifitisonlymadeasymboliclinktoamoreglobalconfigurationfile(perhapsin/usr/etc/X11or

/usr/X11R6/lib/X11).

-22-LinuxFilesystemStructure March28,1995 4.8/usr/local:Localhierarchy The/usr/localhierarchyisforusebythesystemadministratorwheninstallingsoftwarelocally. Itneedstobesafefrombeingoverwrittenwhenthesystemsoftwareisupdated.Itmaybeused forprogramsanddatathatareshareableamongstagroupofmachines,butnotfoundin/usr. /usr/local—Localhierarchy

bin

Local-onlybinaries

doc

Localdocumentation

etc

Configurationforlocal-onlybinaries

games

Locallyinstalledgames

lib

Librariesfor/usr/local

info

Localinfopages

man

Manpagehierarchyfor/usr/local

sbin

Local-onlysystemadministration

src

Localsourcecode ThisdirectoryshouldalwaysbeemptyafterfirstinstallingLinux.Noexceptionstothisrule shouldbemadeotherthanthelisteddirectorystubs. Locallyinstalledsoftwareshouldbeplacedwithin/usr/localratherthan/usrunlessitisbeing installedtoreplaceorupgradesoftwarein/usr. Notethatsoftwareplacedin/or/usrmaybeoverwrittenbysystemupgrades(thoughwe recommendthatdistributionsdonotoverwritedatain/etcunderthesecircumstances).Forthis reason,localsoftwareshouldnotbeplacedoutsideof/usr/localwithoutgoodreason. 4.9/usr/man:Manualpages Thissectiondetailstheorganizationformanualpagesthroughoutthesystem,including

/usr/man.

Manualpagesarestoredin<mandir>/<locale>/man[1-9].Anexplanationof<mandir>and <locale>isgivenbelow. <mandir>/<locale>—Amanualpagehierarchy

man1

Userprograms

man2

Systemcalls

man3

Libraryfunctionsandsubroutines

man4

Devices

man5

Fileformats

man6

Games

man7

Miscellaneous

man8

Systemadministration

man9

Kernelinternalvariablesandfunctions Theprimary<mandir>ofthesystemis/usr/man./usr/mancontainsmanualinformationfor commandsanddataunderthe/and/usrfilesystems.Obviously,therearenomanualpagesin/ -23-LinuxFilesystemStructure March28,1995 becausetheyarenotrequiredatboottimenoraretheyrequiredinemergencies. Provisionsmustbemadeinthestructureof/usr/mantosupportmanualpageswhicharewritten indifferent(ormultiple)languages.Theseprovisionsmusttakeintoaccountthestorageand referenceofthesemanualpages.Relevantfactorsincludelanguage(includinggeographical-based differences),andcharactercodeset. Thisnamingoflanguagesubdirectoriesof/usr/manisbasedonAppendixEofthePOSIX1003.1 standardwhichdescribesthelocaleidentificationstring—themostwellacceptedmethodto describeaculturalenvironment.The<locale>stringis:

<language>[_<territory>][.<character-set>][,<version>]

The<language>fieldshallbetakenfromISO639(acodefortherepresentationofnamesof languages).Itshallbetwocharacterswideandspecifiedwithlowercaselettersonly. The<territory>fieldshallbethetwo-lettercodeofISO3166(aspecificationofrepresentations ofcountries),ifpossible.(Mostpeoplearefamiliarwiththetwo-lettercodesusedforthecountry codesinemailaddresses.1)Itshallbetwocharacterswideandspecifiedwithuppercaseletters only. The<character-set>fieldshouldrepresentthestandarddescribingthecharacterset.Ifthe <character-set>fieldisjustanumericspecification,thenumberrepresentsthenumberofthe internationalstandarddescribingthecharacterset.Itisrecommendedthatthisbeanumeric representationifpossible(ISOstandards,especially),notincludeadditionalpunctuationsymbols, andthatanylettersbeinlowercase. Aparameterspecifyinga<version>oftheprofilemaybeplacedafterthe<character-set> field,delimitedbyacomma.Thismaybeusedtodiscriminatebetweendifferentculturalneeds; forinstance,dictionaryorderversusamoresystems-orientedcollatingorder.Thisstandard recommendsnotusingthe<version>field,unlessitisnecessary. Systemswhichuseauniquelanguageandcodesetforallmanualpagesmayomitthe<locale> substringandstoreallmanualpagesin<mandir>.Forexample,systemswhichonlyhaveEnglish manualpagescodedwithASCII,maystoremanualpages(theman[1-9]directories)directlyin /usr/man.(Thatisthetraditionalcircumstanceandarrangement,infact.) Countriesforwhichthereisawellacceptedstandardcharactercodesetmayomitthe <character-set>field,butitisstronglyrecommendedthatitbeincluded,especiallyfor countrieswithseveral"competing"standards. Variousexamples: LanguageTerritoryCharacterSetDirectory English—ASCII/usr/man/en EnglishUnitedKingdomASCII/usr/man/en_GB EnglishUnitedStatesASCII/usr/man/en_US FrenchCanadaISO8859-1/usr/man/fr_CA 1.

AmajorexceptiontothisruleistheUnitedKingdom,whichis‘GB’intheISO3166,but‘UK’formostemail addresses. -24-LinuxFilesystemStructure March28,1995 FrenchFranceISO8859-1/usr/man/fr_FR GermanGermanyISO646-DE/usr/man/de_DE.646de GermanGermanyISO6937/usr/man/de_DE.6937 GermanGermanyISO8859-1/usr/man/de_DE.88591 GermanSwitzerlandISO646-CH/usr/man/de_CH.646ch

JapaneseJapanJIS/usr/man/ja_JP.jis
JapaneseJapanSJIS/usr/man/ja_JP.sjis

JapaneseJapanUJIS(orEUC-J)/usr/man/ja_JP.ujis Manualpagesforcommandsanddataunder/usr/localarestoredin/usr/local/man.Manual pagesfortheXWindowSystemarestoredin/usr/X11R6/man.Itfollowsthatallmanualpage hierarchiesinthesystemshouldhavethesamestructureas/usr/man.Emptydirectoriesmaybe omittedfromamanualpagehierarchy.Forexample,if/usr/local/manhasnomanualpagesin section4(Devices),then/usr/local/man/man4maybeomitted. Thecatpagesections(cat[1-9])containingformattedmanualpageentriesarealsofoundwithin subdirectoriesof<mandir>/<locale>,butarenotrequirednorshouldtheybedistributedinlieu ofnroffsourcemanualpages. TheMHmailhandlingsystemmanualpagesshouldhavemhappendedtoallmanualpage filenames.AllXWindowSystemmanualpagesshouldhaveanxappendedtothefilename. Thepracticeofplacingvariouslanguagemanualpagesinappropriatesubdirectoriesof/usr/man alsoappliestotheothermanualpagehierarchies,suchas/usr/local/manand/usr/X11R6/man. (Thisportionofthestandardalsoapplieslaterinthesectionontheoptional/var/catman structure.) Adescriptionofeachsectionfollows: •man1:Userprograms Manualpagesthatdescribepubliclyaccessiblecommandsarecontainedinthischapter. Mostprogramdocumentationthatauserwillneedtouseislocatedhere. •man2:Systemcalls Thissectiondescribesallofthesystemcalls(requestsfortheLinuxkerneltoperform operations). •man3:Libraryfunctionsandsubroutines Section3describesprogramlibraryroutinesthatarenotdirectcallstokernelservices.This andchapter2areonlyreallyofinteresttoprogrammers. •man4:Specialfiles Section4describesthespecialfiles,relateddriverfunctions,andnetworkingsupport availableinthesystem.Typically,thisincludesthedevicefilesfoundin/devandthekernel interfacetonetworkingprotocolsupport. •man5:Fileformats Theformatsformanynonintuitivedatafilesaredocumentedinthesection5.Thisincludes variousincludefiles,programoutputfiles,andsystemfiles. •man6:Games Thischapterdocumentsgames,demos,andgenerallytrivialprograms.Differentpeople havevariousnotionsabouthowessentialthisis. -25-LinuxFilesystemStructure March28,1995 •man7:Miscellaneous Manualpagesthataredifficulttoclassifyaredesignatedasbeingsection7.Thetroffand othertextprocessingmacropackagesarefoundhere. •man8:Systemadministration Documentationforprogramsusedbysystemadministratorsforsystemoperationand maintenancearedocumentedhere.Someoftheseprogramsarealsooccasionallyusefulfor normalusers. •man9:Kernelinternalvariablesandfunctions ThisisusedonLinuxsystemstodocumentthekernelsourcecode. 4.10/usr/sbin:Non-essentialstandardsystembinaries Thisdirectorycontainsanynon-essentialbinariesusedexclusivelybythesystemadministrator. Systemadministrationprogramsthatarerequiredforsystemrepair,systemrecovery,mounting /usr,orotheressentialfunctionsshouldbeplacedin/sbininstead. Typically,/usr/sbincontainsnetworkingdaemons,anynon-essentialadministrationtools,and binariesfornon-criticalserverprograms.Thisincludesinternetdaemonscalledbyinetd(named in.*)suchasin.telnetdandin.fingerdandrpc-baseddaemonshandledbyportmap(named

rpc.*)suchasrpc.nfsdandrpc.mountd.

TheseserverprogramsareusedwhenenteringtheSystemVstatesknownas"runlevel2"(multiuserstate)and"runlevel3"(networkedstate)ortheBSDstateknownas"multi-usermode".At thispointthesystemismakingservicesavailabletousers(e.g.,printersupport)andtoother machines(e.g.,NFSexports). Locallyinstalledsystemadministrationprogramsshouldbeplacedin/usr/local/sbin. 4.11/usr/share:Architecture-independentdata Anyspecificationsfor/usr/sharewillbeincludedinasupplementarydrafttothemainFSSTND standard.NotethatitistheconsensusopinionofFSSTNDthat/usr/shareisnotneededonthe majorityofLinuxsystems.Atthistime,confiningourselvesbyprovidinganextensivedefinition ofthisdirectorywouldbeabadidea. Pleaserefertosection6formoredetaileddiscussionof/usr/share. 4.12/usr/src:Sourcecode /usr/src—Sourcecode

linux

SourcecodeforLinuxkernel Anynon-localsourcecodeshouldbeplacedinthissubdirectory.Theonlysourcecodethat shouldalwaysbeplacedinaspecificlocationisthekernelsource(whenpresentorlinkedinpart tothe/usr/includestructure).Subdirectoriesmaybeusedhereifdesired. Thesourcecodeforthekernelshouldalwaysbeinplaceoratleasttheincludefilesfromthe kernelsource.Thosefilesarelocatedinthesedirectories: -26-LinuxFilesystemStructure March28,1995

/usr/src/linux/include/asm-<arch>
/usr/src/linux/include/linux

/usr/includeshouldcontainlinkstothesedirectories,namedasmandlinux.Sincetheyare neededbytheCcompiler,atleastthoseincludefilesshouldalwaysbedistributedwith installationswhichincludeaCcompiler.Theyshouldbedistributedinthe/usr/src/linux directorysotherearenoproblemswhensystemadministratorsupgradetheirkernelversionfor thefirsttime. /usr/src/linuxmayalsobeasymboliclinktoakernelsourcecodetree.

LinuxFilesystemStructure March28,1995 5.The/varHierarchy /var—Variabledata

adm

Systemadministrativedata(obsolete),symboliclinkto/var/log

catman

Locally-formattedmanualpages

lib

Applicationstateinformation

local

Variabledataofsoftwarefrom/usr/local

lock

Lockfiles

log

Logfilesanddirectories

named

DNSfiles,networkingonly

nis

NetworkInformationService(NIS)databasefiles

preserve

Savedfilesaftercrashorhang-upfromexorvi

run

Filesrelevanttorunningprocesses

spool

Directoriesforqueuedworktobeperformedlater

tmp

Temporaryfiles,usedtokeep/tmpsmall /varcontainsvariabledatafiles.Thisincludesspooldirectoriesandfiles,administrativeand loggingdata,andtransientandtemporaryfiles. Someportionsof/vararenotshareablebetweendifferentsystems.Forinstance,/var/log, /var/lock,and/var/run.Otherportionsareshareable,notably/var/spool/mailand

/var/spool/news.

/varisspecifiedhereinordertomakeitpossibletomount/usrread-only.Everythingthatonce wentinto/usrthatiswrittentoduringsystemoperation(asopposedtoinstallationandsoftware maintenance)shouldbein/var. If/varcannotbemadeaseparatepartition,itisoftenpreferabletomove/varoutoftheroot partitionandintothe/usrpartition.(Thisissometimesdonetoreducethesizeoftheroot partitionorwhenspacerunslowintherootpartition.)However,/varshouldnotbelinkedto /usrbecausethismakesseparationof/usrand/varmoredifficultandislikelytocreatea namingconflict.Instead,link/varto/usr/var. 5.1/var/adm:Systemloggingandaccountingfiles(obsolete) Thisdirectoryhasbeensupersededby/var/logandotherdirectories.Itshouldbeasymbolic linkto/var/loguntilallprogramsnolongerrefertoanyfilesin/var/adm. utmphasbeenmovedto/var/run.Alllogfileshavebeenmovedto/var/log,includingthewtmp file. Distributionpackagingsupportshouldbestoredin/var/lib/<name>. Note:the/var/admsymboliclinkshouldnotbenecessaryonmostlinux-i386ELFsystemssince thechangewasintroducedbeforeELFwasreleasedtothepublic. 5.2/var/catman:Locally-formattedmanualpages(optional) Thisdirectoryprovidesastandardlocationforsitesthatprovidearead-only/usrpartition,but wishtoallowcachingoflocally-formattedmanpages.Sitesthatmount/usraswritable(e.g., -28-LinuxFilesystemStructure March28,1995 single-userinstallations)maychoosenottouse/var/catmanandwriteformattedmanpagesinto thecat[1-9]directoriesin/usrdirectly.Werecommendthatmostsitesuseoneofthefollowing optionsinstead: •Preformatallmanualpagesin/usrwiththecatmanprogram. •Allownocachingofformattedmanpages,andrequirenrofftoberuneachtimeaman pageisbroughtup. •Allowlocalcachingofformattedmanpagesin/var/catman. Thestructureof/var/catmanneedstoreflectboththefactofmultiplemanpagehierarchiesand thepossibilityofmultiplelanguagesupport. Givenanunformattedmanualpagethatnormallyappearsin/usr/<path1>/man/man[1-9],the cachedformattedversionshouldgoin/var/catman/<path2>/cat[1-9],where<path2>is <path1>.The<path1>and<path2>componentsareabsentinthecaseof/usr/manand

/var/catman.
Forexample,/usr/man/man1/ls.1isformattedinto/var/catman/cat1/ls.1,and
/usr/X11R6/man/<locale>/man3/XtClass.3xinto
/var/catman/X11R6/<locale>/cat3/XtClass.3x.

Manpageswrittento/var/catman/cat[1-9]mayeventuallybetransferredto

/usr/<path>/cat[1-9]orexpired;likewiseformattedmanpagesin/usr/<path>/cat[1-9]may

beexpirediftheyarenotaccessedforaperiodoftime. IfpreformattedmanualpagescomewithaLinuxsystemonread-onlymedia(aCD-ROM,for instance),theyshallbeinstalledinto/usr/<path>/cat[1-9]./var/catmanisreservedasa writeablecacheforformattedmanualpages. 5.3/var/lib:Applicationstateinformation /var/lib—Applicationstateinformation

emacs

StatedirectoryforEmacs

games

Variablegamedata(scorefiles)

news

VariablefilesforCnews/INN

texmf

VariabledataassociatedwithTEX

xdm

Xdisplaymanagerauthenticationfilesanderrorlogs /var/lib/<name>istheappropriatelocationforalldistributionpackagingsupport.Different Linuxdistributionsmayutilizedifferentnames,ofcourse. 5.3.1/var/lib/emacs TheGNUEmacsstatedirectory,thelocationofarchitecture-independentdatafilesthatEmacs modifieswhilerunning,shouldbe/var/lib.Presently,Emacsonlylocatesitslockfiledirectory underthestatedirectory(in<statedir>/emacs/lock),butitmaymakemoreextensiveuseof thestatedirectoryinthefuture.Notably,itonlyrequirestheadditionofasingleoptiontothe Emacsconfigureprogramtomakethischange(beforecompilation). -29-LinuxFilesystemStructure March28,1995 5.3.2/var/lib/games Aswellasthesubdirectorieslistedabove,anyvariabledatarelatingtothegamesfoundin /usr/gamesshouldbeplacedhere./var/lib/gamesshouldholdthevariabledatapreviously foundin/usr/lib/games;staticdata,suchashelptext,leveldescriptions,andsoon,should

remainin/usr/lib/games.

5.3.3/var/lib/news /var/lib/newsshouldbeusedtostoreallthevariabledataassociatedwithnewsserverssuchas CnewsandINN,includingthehistoryfile,activefile,andsoforth. 5.3.4/var/lib/texmf /var/lib/texmfshouldbeusedtostorethevariabledataassociatedwithTEX.Inparticular, /var/lib/texmf/fontswillstoreallofthefontswhichareautomaticallygeneratedby

MakeTeXPK.
Thereshouldbealinkfrom/usr/lib/texmf/fonts/tmpto/var/lib/texmf/fonts.Thislink

allowsuserstousesinglepath/usr/lib/texmf/fonts/tfmwhenmakingchangestotheir TEXFONTSenvironmentvariable.(ThisisthedefaultpathforKarlBerry’sTEXtools, distributedfromftp.cs.umb.edu:/pub/tex.2IfanotherTEXdistributionisused,alinkfromthe appropriatefontdirectoryto/var/lib/texmf/fontsshouldbemade.) TheMakeTeXPKthatisdistributedwithdvipskwillplace.pkfilesin

fonts/pk/<device>/<fontname>(e.g.,fonts/pk/CanonCX/cmr10.300pk).The.pkfilescanbe

periodicallypurgedfromthe/var/lib/texmftree,orcanbemovedintothe/usr/lib/texmf tree.Ifautomatic.mfor.tfmgeneratorsareused,theyshouldplacetheirdatainthemfortfm

subdirectoriesof/var/lib/texmf/fonts.

5.3.5/var/lib/xdm /var/lib/xdmcontainsthevariabledatafromxdm,whichconsistsofthexdm-errorsfilesand anyxdmauthorityfiles.xdmbinariessuchasthechoosershouldstillbeplacedinthehistorical

locationin/usr/X11R6/lib/X11/xdm.Thexdm-pidfileshouldbeplacedin/var/lib/xdm

despitetheexistenceof/var/run.Theremainingfilesshouldbeplacedin/etc/X11/xdm. 5.4/var/local:Variabledataofsoftwarefrom/usr/local Thisdirectorycontainsallvariabledatawhichisrelatedtosoftwarefoundin/usr/local. Naturally,theimplementationofthisdirectoryisleftuptothesiteadministrator.However, informationwhichcanbecategorizedintoanother/vardirectoryshouldnotbeplacedin /var/local.Forexample,alllockfilesstillgointo/var/lock. 2.

ThereasonthatKarlBerry’stoolsarementionedisthattheyarethede-factostandardforUNIXinstallationsof TEX.ThesetoolsarewidelyusedintheLinuxcommunity. -30-LinuxFilesystemStructure March28,1995 5.5/var/lock:Lockfiles Lockfilesshouldbestoredwithinthe/var/lockdirectorystructure. Topreservetheabilitytomount/usrread-only,nolockfilesshouldbeplacedonthe/usr partition. Devicelockfiles,suchastheserialdevicelockfileswhichwereoriginallyfoundineither

/usr/spool/locksor/usr/spool/uucp,shouldnowbestoredin/var/lock.Thenaming

conventionwhichshouldbeusedisLCK..followedbythebasenameofthedevice.Forexample, tolock/dev/cua0thefileLCK..cua0wouldbecreated. TheformatusedforLinuxdevicelockfilesshouldbetheHDBUUCPlockfileformat.TheHDB formatistostoretheprocessidentifier(PID)asatenbyteASCIIdecimalnumber,withatrailing newline.Forexample,ifprocess1230holdsalockfile,itwouldcontaintheelevencharacters: space,space,space,space,space,space,one,two,three,zero,andnewline. Then,anythingwishingtouse/dev/cua0canreadthelockfileandactaccordingly(alllocksin /var/lockshouldbeworld-readable). 5.6/var/log:Logfilesanddirectories Thedirectorycontainsmiscellaneouslogfiles.Mostlogsshouldbewrittentothisdirectoryoran appropriatesubdirectory. lastlogrecordoflastloginofeachuser messagessystemmessagesfromsyslogd wtmprecordofallloginsandlogouts Asymboliclinkfrom/var/log/utmpto/var/run/utmpmayberequireduntilprogramsno longerreferto/var/adm/utmp(/var/admisitselfatransitionalsymboliclinkto/var/log). 5.7/var/named:DNSfiles ThisdirectorycontainsalltheworkingfilesoftheInternetnameserver,named. Werecommendthat/etc/named.bootbeasymboliclinkto/var/named/named.bootsince /etc/named.bootisthedefaultbootfileifnoargumentsaregiventonamed. 5.8/var/nis:NetworkInformationService(NIS)databasefiles TheNetworkInformationService(NIS)wasformerlyknownastheSunYellowPages(YP).The functionalityanddirectoryplacementofthetwoisthesame,butthename"YellowPages"isa registeredtrademarkintheUnitedKingdom,belongingtoBritishTelecommunicationsplc,and maynotbeusedwithoutpermission. 5.9/var/preserve:Savedfilesaftercrashorhang-upfromexorvi Thisdirectorycontainssavedfilesgeneratedbyanyunexpectedterminationofex,vi,ortheir clones. -31-LinuxFilesystemStructure March28,1995 5.10/var/run:Run-timevariablefiles Thisdirectorycontainssysteminformationfilesdescribingthesystemsinceitwasbooted. Generally,filesinthisdirectoryshouldbecleared(removedortruncatedasappropriate)the beginningofthebootprocess. Processidentifier(PID)files,whichwereoriginallyplacedin/etc,areplacedin/var/run.The namingconventionforPIDfilesis<program-name>.pid.Forexample,thecrondPIDfileis

named/var/run/crond.pid.

TheinternalformatofPIDfilesremainsunchanged.Thefileshouldconsistoftheprocess identifierinASCII-encodeddecimal,followedbyanewlinecharacter.Forexample,ifcrondwas processnumber25,/var/run/crond.pidwouldcontainthreecharacters:two,five,andnewline. ProgramsthatreadPIDfilesshouldbesomewhatflexibleinwhattheyaccept;i.e.,theyshould ignoreextrawhitespace,leadingzeroes,absenceofthetrailingnewline,oradditionallinesinthe PIDfile.ProgramsthatcreatePIDfilesshouldusethesimplespecificationlocatedintheabove paragraph. Theutmpfile,whichstoresinformationaboutwhoiscurrentlyusingthesystem,islocatedinthis directory. ProgramsthatmaintaintransientUNIX-domainsocketsshouldplacetheminthisdirectory. 5.11/var/spool:Spooldirectories /var/spoolistraditionallyusedformachine-localdatabeingspooledtoorfromUNIX subsystems.Forexample,printjobsarespooledherefordeliverytothelineprinterdaemon,outboundmailisspooledfordeliverytoremotesystems,andUUCPfilesarespooledfortransmission toUUCPneighbors.In-boundmailandnewsarespooledherefordeliverytousers,andatand cronjobsarespooledfordelayedexecutionbythecrondaemon. /var/spool—Spooldirectories

at

atjobs

cron

cronjobs
lpd

Printerspooldirectory

mail

Usermailboxfiles

mqueue

Outgoingmailqueue

news

Newsspooldirectory

rwho

Rwhodfiles

smail

Spooldirectoriesforsmail

uucp

SpooldirectoryforUUCP UUCPlockfilesshouldbeplacedin/var/lock.Seetheabovesectionon/var/lock. 5.11.1/var/spool/lpd -32-LinuxFilesystemStructure March28,1995 /var/spool/lpd—Printerspooldirectory

<printer>

Spoolsforaspecificprinter Thelockfileforlpd,lpd.lock,shouldbeplacedin/var/spool/lpd.Thelockfileforeach printershouldbeplacedinthespooldirectoryforthatspecificprinterandnamedlock. 5.12/var/tmp:temporaryfiles,usedtokeep/tmpsmall Filesin/var/tmparestoredforanunspecifiedduration(pleaserememberthatsystemtemporary directoriesarenotguaranteedtoholddataforanyparticularduration). Datastoredin/var/tmpistypicallycleanedout"inasite-specificmanner",butusuallyatless frequentintervalsthan/tmp.Moreinformationontemporarydirectoriesisinthesectionofthe standarddevotedto/tmp(above). Thereshouldbeasymboliclinkfrom/usr/tmpto/var/tmp,forcompatibilityreasons.

LinuxFilesystemStructure March28,1995 6.IssuesandAdditionalRationale Thissectiondiscussesseveralareasthatmayrequirefurtherexplanation. 6.1WhatisEssential? Theansweris:essentialtoclean,create,prepare,check,findandmountotherfilesystems (possiblyonremotemachines).Thereareotherdefinitions,butthisisageneraldefinitionthat mostpeoplewillatleastincorporateintotheirown. 6.2Networking Networkingpresentedaninterestingdilemma.Somepeoplewantedtoseparatenetworking binariesandconfigurationfromotherbinariesandconfiguration.However,wedisagree.Wefeel thatnetworkingisnota"package",butanintegralpartofmostUNIX(andUNIX-like)machines. Becauseofthisnetworkingshouldnotbeplacedintoasingledirectory,butsystematicallyplaced intheappropriatedirectories. •/bin:anythingauserwillwanttousethatisalsoconsideredvital

{hostname,netstat,ping}

•/sbin:anythingonlyrootneedsandisconsideredvital

{arp,ifconfig,route}

•/usr/bin:anybinariesauserwillwanttouse,andwhicharenotvital

{finger,rcp,rlogin,telnet,etc.}

•/usr/sbin:anyadministratoronlybinariesthatarenotvital

{in.ftpd,inetd,lpd,portmap,etc.}

Whilethismayseemconfusingatfirst(anditdoestakeamomenttodigest),itdoesmakesense. Ifyoucanonlymountrootforsomereasonandyouneedaccesstonetworkingtorepairyour system,youdon’tneedthefilestobeoffin/usr/etc(astheyoftenare).Filesthatareneededto mount/usrinnormal(andemergency)situationsareplacedontherootsubtreeandanyothers areplacedin/usrinordertokeepthesizeoftherootfilesystemsmall. Configurationfilesfornetworkingbelongin/etc. 6.3Architecture-independentStructures Thedirectory/usr/sharetypicallycontainsarchitecture-independentfilessuchasman-pages, timezone,terminfoinformation,etc.Asofthistime,therearenodifferentarchitecturesfor Linux,butwiththepassageoftimeweshouldseeLinuxincludeotherarchitecturesandother UNIX-likesystems. Onenote:noprogramshouldeverreferenceanythingin/usr/share.Forinstance,amanualpage programshouldneverdirectlylookin/usr/share/man/man1/ls.1,butitshouldreferto /usr/man/man1/ls.1atalltimes.Anythingin/usr/sharewillbe"pointedto"bytheuseof symlinksfromotherareasinthefilesystem,suchas/usr/man,/usr/lib/<something>,etc. Thespecificationsfor/usr/sharearestillbeingworkedon. -34-LinuxFilesystemStructure March28,1995 6.4SymbolicLinks Thereareawiderangeofusesforsymboliclinksineveryfilesystem.Whilesymlinksarenot encouragedfordefaultsetup(foundafterinstallingLinux)inastandardsuchasthis,theyare oftenusedwithgoodpurposeondifferentsystems.Thepointisthatsymlinksshouldbethereto keepeverythingwhereeveryoneelseexpectsfindit. Bepreparedtoacceptthatcertaindirectories,eventhosecontainedontherootdirectory,arestill goingtobesymlinks.Forinstance,onsomesystems/homewillnotbeontheroot,butsymlinked toa/vardirectory,ortosomewhereelse./homecouldalsohaveitsownphysicalpartition,of course,andbemountedonitsown. Similarly,because/usrmightbeonacentralfileservermountedviaNFS,/usr/localcouldbe symlinkedto/var/local.Thischangecanbejustifiedbyrecallingthemainreasonforhaving /var:toseparatedirectoriesoffilesthatvarywithtimeandbetweendifferentsystemsand machinesfromthosethatmaybesharedandread-only. Sometimessystemswillalsolink/tmpto/var/<something>iftherootpartitionbecomestoo small(orstartsouttoosmall).Therearemoreexamplesof"good"usesofsymboliclinks,but theentireissueboilsdowntotwothings:packagesshouldbeabletofindthingswheretheyexpect them(withinreason)andsymboliclinkscanbeusedtosolvetheprobleminmanycases. However,problemsalsocanarisefromusingtoomanysymboliclinks.Theseproblemsinclude over-relianceonsymboliclinkstosolveproblems,confusionresultingfromoveruseofsymbolic links,andtheaestheticpreferencesofdifferentpeople. 6.5Staticallylinkedbinaries Linuxiscurrentlyrunningonawidevarietyofsystems,somesingleuserwithsmalldisks,someas serversinlargenetworkedenvironments.Becauseofthisvariety,thisstandardsetsnorule regardingwhatbinariesarestaticordynamicwiththefollowingtwoexceptions.Bothlnand syncshouldexistin/bin;anystaticallylinkedversionsmaybeplacedin/sbin,orreplacethose

in/bin.

LargeLinuxsystemsmaywishtoincludeotherstaticallylinkedbinaries(sh,init,mkfs,fsck,

tunefs,mount,umount,swapon,swapoff,getty,login,andothers).Developersand/orsystem

administratorsarefreetostatically/dynamicallylinktheseandotherbinariesastheyseefit,as longasthelocationofthebinariesdoesn’tchange. Networkedsystems(especiallyonesthatdon’thavefloppydrives),maywanttolinkifconfig, route,hostname,andothernetworkingutilitiesstaticallyaswell.Thisisusuallynotneeded. -35-LinuxFilesystemStructure March28,1995 TheFSSTNDmailinglist TheFSSTNDmailinglistislocatedat<linux-fsstnd@ucsd.edu>.Thislistwasoriginallylocated onthe<linux-activists@Niksula.hut.fi>"Mail-Net"astheFSSTNDchannel.(Tosubscribetothe listsendmailto<listserv@ucsd.edu>withbody"ADDlinux-fsstnd".) ThankstoNetworkOperationsattheUniversityofCaliforniaatSanDiegowhoallowedustouse theirexcellentmailinglistserver. Asnotedintheintroduction,pleasedonotsendmailtothemailinglistwithoutfirstcontacting theFSSTNDcoordinatororalistedcontributor. Acknowledgments CreditforthistextshouldbegiventotheFSSTNDactivists,developers,systemadministrators, anduserswhoseinputwasessentialtothisstandard.Ialsowishtothankeachofthe contributorswhohelpedmetowrite,compile,andcomposethis,aconsensusstandard. IalsowishtogiverealcredittothoseLinuxdeveloperswhohaveseenthatgivingLinuxa commonfilesystemlayoutissomethingthatwillfurtherthedevelopmentoftheLinuxoperating system.IalsowishtonotethebraveryandperseveranceofthoseLinuxdeveloperswhostarted followingthisstandardbeforeitwascompleted. Originalcontributors DrewEckhardt<drew@colorado.edu> IanJackson<ijackson@cus.cam.ac.uk> IanMcCloghrie<ian@ucsd.edu> DanielQuinlan<Daniel.Quinlan@linux.org> MikeSangrey<mike@sojurn.lns.pa.us> DavidH.Silber<dhs@glowworm.firefly.com> TheodoreTs’o<tytso@athena.mit.edu> StephenTweedie<sct@dcs.ed.ac.uk> Additionalcontributors BrandonS.Allbery<bsa@kf8nh.wariat.org> RikFaith<faith@cs.unc.edu> StephenHarris<sweh@spuddy.mew.co.uk> FredN.vanKempen<waltje@infomagic.com> JohnA.Martin<jmartin@csc.com> ChrisMetcalf<metcalf@lcs.mit.edu> IanMurdock<imurdock@debian.org> DavidC.Niemi<niemidc@clark.net> -36-CONTENTS 1.

General ................................................................................................................................2 1.1 Scope ...........................................................................................................................2 1.2 SpecificProblems ........................................................................................................3 1.3 Objectives ...................................................................................................................4 1.4 HistoryandProgress ...................................................................................................4 1.5 ConformancewiththisDocument ...............................................................................5 2.

TheFilesystem ....................................................................................................................7 3.

TheRootDirectory .............................................................................................................9 3.1 /bin:Essentialusercommandbinaries(forusebyallusers)

...................................10 3.2 /boot:Staticfilesofthebootloader ........................................................................11 3.3 /dev:Devicefiles ......................................................................................................12 3.4 /etc:Machine-localsystemconfiguration .................................................................12 3.5 /home:Userhomedirectories(optional)

..................................................................13 3.6 /lib:Essentialsharedlibrariesandkernelmodules ..................................................14 3.7 /mnt:Mountpointfortemporarilymountedfilesystems .........................................14 3.8 /proc:Kernelandprocessinformationvirtualfilesystem ........................................14 3.9 /root:Homedirectoryforroot(optional)

................................................................14 3.10 /sbin:Systembinaries(binariesoncekeptin/etc)

..................................................15 3.11 /tmp:Temporaryfiles ..............................................................................................17 4.

The/usrHierarchy ............................................................................................................18 4.1 /usr/X11R6:XWindowSystem,Version11Release6 ............................................19 4.2 /usr/X386:XWindowSystem,Version11Release5,onx86platforms .................19 4.3 /usr/bin:Mostusercommands ................................................................................19 4.4 /usr/dict:Wordlists ................................................................................................20 4.5 /usr/etc:Site-widesystemconfiguration ..................................................................20 4.6 /usr/include:Directoryforstandardincludefiles.

...................................................20 4.7 /usr/lib:Librariesforprogrammingandpackages ...................................................21 4.8 /usr/local:Localhierarchy .......................................................................................23 4.9 /usr/man:Manualpages ..........................................................................................23 4.10 /usr/sbin:Non-essentialstandardsystembinaries ...................................................26 4.11 /usr/share:Architecture-independentdata ..............................................................26 4.12 /usr/src:Sourcecode ...............................................................................................26 5.

The/varHierarchy ............................................................................................................28 5.1 /var/adm:Systemloggingandaccountingfiles(obsolete)

.......................................28 5.2 /var/catman:Locally-formattedmanualpages(optional)

.......................................28 5.3 /var/lib:Applicationstateinformation ....................................................................29 5.4 /var/local:Variabledataofsoftwarefrom/usr/local ..............................................30 5.5 /var/lock:Lockfiles .................................................................................................31 5.6 /var/log:Logfilesanddirectories ............................................................................31 5.7 /var/named:DNSfiles .............................................................................................31 5.8 /var/nis:NetworkInformationService(NIS)databasefiles ....................................31 5.9 /var/preserve:Savedfilesaftercrashorhang-upfromexorvi ...............................31 5.10 /var/run:Run-timevariablefiles .............................................................................32 5.11 /var/spool:Spooldirectories ....................................................................................32 i 5.12 /var/tmp:temporaryfiles,usedtokeep/tmpsmall ...............................................33 6.

IssuesandAdditionalRationale ........................................................................................34 6.1 WhatisEssential?

.....................................................................................................34 6.2 Networking ................................................................................................................34 6.3 Architecture-independentStructures .........................................................................34 6.4 SymbolicLinks ..........................................................................................................35 6.5 Staticallylinkedbinaries ...........................................................................................35